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Preface 



This book contains technical information for the IBM Operating 
System/2™ (0S/2™i). It provides a comprehensive and detailed 
description of OS/2 interfaces. This book also provides descriptions 
of OS/2 architecture, control structures, data structures, and I/O 
formats necessary to understand and use those interfaces. 



This book is intended for the experienced user, system programmer, 
and application developer. You should be knowledgeable about 
operating systems and be proficient In one or more of the IBM Per- 
sonal Computer programming languages, as well as being familiar 
with the 80286 architecture. 
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Chapter 1. Introduction 



OS/2 has three methods of providing system services to application, 
or subsystem, programs: 

• API Function Requests 

• lOCtI Functions 

• DevHIp Services 

The Application Programming Interface (API) function calls provide a 
method for an application, or subsystem, to request OS/2 services 
(function requests). API function requests are invoked by a Call- 
Return interface with the stack used to pass request parameters. 

OS/2 device drivers are used by OS/2 to access the I/O hardware. 
The lOOtl functions provide a method for an application, or sub- 
system, to send device-specific control commands to a device driver. 
The lOCtI functions are issued through the DosDevlOCtI API function 
request. The lOCtl functions are sub-functions of the DosDevlOCtI 
API function request. (For a detailed description of the lOCtI functions 
refer to Technical Reference, Vol. 2.) 

The DevHIp services provide a method for OS/2 device drivers to 
request OS/2 services. Many OS/2 device driver functions are related 
to system operations rather than to hardware operations. The DevHIp 
functions are used to request OS/2 system functions, when writing 
your own OS/2 device driver. 

OS/2 uses OS/2 device drivers to access I/O devices attached to an 
IBM Personal Computer AT® or Personal Computer XT™ Model 286 
or an IBM Personal System/2™. An Application Programmer can 
write programs using the OS/2 device drivers supplied with OS/2, or 
his own OS/2 device driver. 
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API Function Requests 



All OS/2 API function requests are invoked with a CALL interface. 
There are significant advantages when using a CALL programming 
interface if the parameters are "pushed" onto the stacl< before 
issuing the CALL. The hardware actually copies the parameters from 
the requestor's stacl< to the receiving program's stack, thus giving 
optimum addressability and protection at minimal execution cost. 

OS/2 has a Dynamic Link facility by which linkage to a system func- 
tion or routine is not resolved until run time. The Dynamic Link 
facility provides improved storage utilization because common library 
routines need not be linked to each load module. Programs written to 
the OS/2 interface are usually smaller In size (both on disk and in 
memory). 

In addition, a restricted subset of the OS/2 API function requests is 
supported as a DOS Family API. Applications written to this API and 
linked with OS/2 library routines are capable of executing in either 
OS/2 or DOS modes. 

The API Function Requests can be grouped into the following catego- 
ries by function: 

• Memory Management 

• Process Control 

• Session Management 

• I/O Services 

• Country Support 

Memory Management 

OS/2 memory management allows an application to use the 80286 
extended memory (physical storage up to 16Mb). OS/2 memory man- 
agement allows a user to concurrently execute more applications 
than fit in memory. Also, any single application and its data can be 
larger than real memory. OS/2 maintains the most active set of seg- 
ments in memory at any one time by swapping the least active seg- 
ments to disk, then reloading them when needed. 
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The memory management functions allow an application to: 

• Allocate multiple data segments 

• Implement an application as a number of distinct CALLable seg- 
ments with OS/2 providing loading on demand as necessary 

• Explicitly load applications if desired 

• Package an application so that the linkage to library routines or 
infrequently used routines is not made until run time. 

Process Control 

OS/2 process control functions can be grouped into the following cat- 
egories by function: 

• Timer Services 

• Multitasking 

• Interprocess Communication. 
Timer Services 

In addition to the Date and Time functions provided in DOS, OS/2 pro- 
vides the following functions: 

• Regularly occurring intervals 

• Asynchronous intervals 

• Sleep for a period of time. 

Multitasking 

The multitasking functions of OS/2 allow a user to operate several 
applications concurrently. For most purposes, each application 
appears to have the entire computer to itself and may be designed 
and coded in much the same manner as with DOS. An application 
can also be designed such that its functions are divided among a col- 
lection of cooperating processes. 
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Multitasking is an integral part of OS/2. A priority-based, time- 
sharing scheduler is provided with special consideration being 
offered for applications with time-critical response requirements. 
Functions are provided to: 

• Start new processes 

• Start/stop/modify execution threads within a process 

• Coordinate execution among several processes. 

Interprocess Communication 

The interprocess communications (IPC) functions allow processes to 
communicate with one another. These functions allow a program to: 

• Communicate between processes via pipes, signals, queues, 
semaphores, and shared memory 

• Explicitly control other processes execution 

• Control access to serially reusable resources 

• Signal occurrence of a flag event. 

Session Management 

The session management functions of OS/2 allow an application to 
select, set status, start, and stop sessions. 

I/O Services 

OS/2 provides the following I/O services to applications: 

• I/O function calls 

• Code Page support 

• Device Monitor Services 

• Printer/Spooler Services 

OS/2 provides access to I/O through function calls and device drivers. 
Some devices are accessed through function calls specific to the 
device, such as the keyboard (KBD), mouse (MOU), and video I/O 
(VIQ) calls. 
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Code Page Support 



OS/2 Code Page Support allows a user to select a code page for key- 
board input and screen and printer output before running an applica- 
tion, a system command or utility in the OS/2 multitasking 
environment. This allows the user in a particular country such as 
England or Norway or a language region such as Canadian-French to 
run with a code page that defines an ASCII-based character set con- 
taining characters used by that particular country or language. 

Device Monitor Services 

Character Device Monitors provide a mechanism for applications or 
subsystems to monitor all characters passing through a device driver. 
This mechanism allows any registered process to remove, insert or 
modify the information passing through the device. 

Keystrolce IMonitor: A keystroke monitor can pass the keystroke 
through, consume the keystroke, or replace the keystroke with one or 
many keystrokes. Some applications monitor all keystrokes and 
provide global system function before more conventional applications 
receive the keystrokes. Examples Include national language support 
for switching the keyboard layout and for Asian language input con- 
version. 

Printer/Spooler Services 

OS/2 provides printer/spooler services. The primary purpose of the 
spooler is to accumulate data directed to a printer on a per session 
basis. When the application is complete, the data will be output to the 
printer in one contiguous data stream. This reduces the possibility of 
intermixing printed output from different sessions to the same printer. 
The spooler also has the capability of invoking the Code Page 
Switcher which provides functions to allow an application to control 
code pages and fonts. 
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DevHIp Services 



Device driver lielper routines are provided for managing the request 
queue, blocking and unblocking, locking and unlocking memory. 

Access to tliese system services is obtained at tlie time of device 
driver initialization. The request packet for the INIT command con- 
tains a pointer to the DevHIp interface. The pointer to the DevHip 
interface is a bimodal pointer; that is, this pointer to the DevHIp inter- 
face Is valid In both real mode and protect mode. The device driver 
does not have to be sensitive to the mode of operation before 
requesting DevHIp services. 

A DevHIp service is invoked by setting up the appropriate registers, 
loading a function code into the DL register, and making a FAR CALL 
to the DevHIp Interface routine, whose address was supplied at 
device driver initialization time. 



OS/2 Device Driver Architecture 

OS/2 device drivers are divided into two parts - a strategy routine and 
an Interrupt routine: 

• The strategy routine Is called with an i/0 packet which describes 
the request. The strategy routine marks the request incomplete 
and queues the request. If the device is not busy it starts the 
device. Then it returns to the kernel which typically blocks on the 
incomplete I/O packet. 

• The interrupt routine services the I/O completion. If there is new 
work in the queue, it starts the device. Then it indicates that the 
previous operation Is complete and unblocks any threads which 
are waiting for this request to be completed. 
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OS/2 Device Drivers 



The device drivers provided with OS/2 service requests in both the 
DOS mode and the OS/2 mode. Where appropriate, OS/2 device 
drivers provide a queued request interface rather than the serial 
request design of DOS device drivers. OS/2 device drivers support 
multitaslcing. 

The device drivers supplied with OS/2 are: 

• Asynchronous Communication (RS-232) 

• Mouse Device Drivers 

• Pointer Draw Device Driver 

• VDisk 

• CLOCKS 

• Console (Screen and Keyboard) 

• Screen (OS/2 mode) 

• Keyboard (OS/2 mode) 

• EGA Register Interface (DOS mode) 

• Diskette 

• Fixed Disk 

• Printer 



Problem Determination 

OS/2 provides a system trace for problem determination. 



Country Support Considerations 

Country Support for OS/2 includes these features: 

• Country Dependent Information 

• Country APIs 

• National Keyboard Layouts 

• Configuration Commands 

• Translation of System Message Files 
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Chapter 2. Application Program interface 
(APi) 



The OS/2 Application Programming Interface (API) represents 
requests for system services. The API functions are involved by a 
CALL-RETURN interface with the stack being used to pass the request 
parameters. The most obvious benefits are: 

• Less need for a high-level language system services library — the 
respective function call may be interfaced directly from a high- 
level language such as IBM 

• Optimum performance — the target routine may be invoiced 
directly rather than having an intermediary "router" get control 
first. 

• The same interface mechanism is available for invoking an OS/2 
routine as well as a library routine. 

• Function replacement is an architected and well-defined activity. 

When using the multiple protection rings of the 80286, there are sig- 
nificant advantages to a CALL programming interface if the parame- 
ters are "pushed" onto the stack before issuing the CALL. The 
hardware actually copies the parameters from the requestor's stack 
to the receiving program's stack, thus giving addressability and pro- 
tection at minimal execution cost. All OS/2 functions are invoked via 
the CALL interface. A means to similarly call system extensions and 
I/O privilege routines executing at protection ring 2 is also provided. 
The application interface to the OS/2 mode and device drivers is 
strictly hierarchical, and the 80286 hardware supports and enforces 
this hierarchy. 



1 C/2 is a trademark of International Business Machines Corporation. 
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Dynamic Linking 



The 80286 protect mode CALL architecture also offers benefits of 
greater importance than hierarchical structure and data copying. In 
particular, the following are definite advantages over the typical static 
module structure of DOS: 

• Application programs need only load the most commonly used 
segments when started. Exception processing routines do not 
need to be loaded. They can be called (and be automatically 
loaded by the system) as necessary. 

• Dynamic link package updates can be transparent to their clients. 
Existing applications can use enhanced function calls in a 
dynamic link package, and the existing applications need not 
change. 

The actual programming steps required to use the dynamic link 
feature are the same as those of a static environment. The steps are: 

1. The programmer codes a call to a subroutine which is to be 
dynamically linked and declares it "EXTERNAL FAR". 

2. The compiler generates a standard external reference. 

3. When the object module Is linked, the linker is provided with the 
names of libraries containing dynamic link definition records. 
These records provide correspondence between the called entry 
point and the module file containing the routine being called. 

PC Family API 

In developing a single product to be used on either OS/2 or DOS 3.3, 
application developers can use a subset of the full function OS/2 API. 
This subset is the DOS Family API. An application that is written to 
this subset functions on either system. 

The interface to the target operating system is provided as a set of 
program modules. These modules are loaded only when executing in 
a DOS mode. 

Note: After compiling or assembling and linking for OS/2, you must 
BIND your .EXE file in order to make it run in both the OS/2 and DOS 
modes. 
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OS/2 Function Calls 



This section describes liow OS/2 function calls are issued. OS/2 
applications must use the dynamic link mechanism (FAR CALL) to get 
to all services. The old style (INT 21 H ...) function calls are supported 
only for the DOS mode. 



OS/2 Function Call Rules 

Rules for the OS/2 interface are shown below: 

Rule 1: All parameters are passed on the stack (SS:SP). 

Remarks Passing parameters on the stack is consistent across a 
broad base of languages on the 80286 family of 
processors. This method allows direct access to the oper- 
ating system from high order languages. The minimum 
recommended stack space available is 2K bytes. 



Rule 2: All interfaces pass a return code back to the caller in AX. 

Remarks The use of register AX as a function return code is also 
consistent across many languages. All user registers 
except the FLAGS register are preserved. The contents of 
the FLAGS register are undefined. The state of the direc- 
tion flag in the FLAGS register is preserved. If the direc- 
tion flag was clear when an API was called then it will be 
clear when the API returns. 



Rule 3: All addresses of OUTPUT parameters are of the form: 
selector: offset. 

Remarks Fully qualified addresses are available across all memory 
models as a method for returning values to a requestor. 
This allows one function entry point to serve all languages 
and memory models. 
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Rule 4: Each function is accessed by a FAR CALL. 

Remarks This is a requirement for the functions to be dynamic linic 
entries. 



Rule 5: All functions remove the parameters from the stack. 

Remarks Parameter lists are fixed length on a function basis. Vari- 
able length parameter lists are not supported. 



Rule 6: All function names must be upper case at linl< time. 

Remarks If a compiler or assembler generates case-sensitive 

(upper and lower case) external references, all calls or 
function definitions must be in all UPPER case characters. 



OS/2 Function Call Characteristics 

The function call descriptions follow a pseudo assembly language 
format. The interfaces are shown to be descriptive rather than to be 
an example of a coding sequence. The conventions described below 
are employed throughout this book. 

Function Call Format 

Because all parameters are pushed onto the stack, there are several 
pseudo Instructions to describe these operations. 

• PUSH - push an item onto the stack 

This can be used to push various size Items onto the stack. The 
data item types are described below. 

• PUSH@ - push the address of an item onto the stack 

All addresses in these interfaces are composed of a 32-bit value: 
a 16-bit selector, and a 16-bit offset. This address can point to 
any of the data item types. 

• CALL - call a function 

All function calls are accessed via FAR CALLs. This is a require- 
ment to utilize the Dynamic Link mechanism. 



2-4 



The following are data item types used to make up a parameter list: 

• WORD - 2 bytes 

This type of operand can be passed by value (pushed onto the 
stack) or by reference (the address of the operand is passed on 
the stack). 

• DWORD -4 bytes 

This type of operand can be passed by value (pushed onto the 
stack) or by reference (the address of the operand is passed on 
the stack). 

• ASCIIZ - null (0) terminated character string 

This type of operand can be accessed only by reference. 

• Other - any other structure 

This type of operand can be accessed only by reference. 
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Interface Stack Frame 



All parameters are passed via the stack. An example stack frame is 
shown below: 



(HIGH ADDRESS) 



These items 
are pushed 
on the stack 
by the caller. 



This is pushed 
on the stack 
by a FAR CALL 
to the function. 

I 

(LOW ADDRESS) 



Parameter 1 
(push WORD) 



Parameter 2 (segment) 



(offset) 



more Parameters 



Parameter N 
(push WORD) 



caller's OS 



caller's IP 



These are 
removed by 
the RET from 
the function. 



This is removed 
by the RET from 
the function. 



The following is the calling sequence that corresponds to the diagram 
above. 



PUSH 
PUSH® 



WORD 



Parameter 1 
Parameter 2 



PUSH 
CALL 



WORD 



Parameter N 
f uncti on 
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Function Calling Sequence Example 

This is a sample function call. In Technical Reference, Vol. 2, the 
function calling sequence is shown using pseudo code. The pseudo 
code is similar to IBM Personal Computer Macro Assembler. Some 
definitions and necessary statements for segments and procedures 
are left out. The following example shows how a function call builds 
a stack and also how the pseudo code relates to actual code. 

Pseudo Code Actual Code 



extrn DOSXAMPLrfar extrn DOSXAMPL:far 



; these items are in DS 



INI 
IN2 



dw 
db 



44 



X 



OUTl 



dw 



6 



PUSH WORD INI 



push INI 



PUSH@ WORD OUTl 



push ds 

mov ax, off set OUTl 
push ax 



PUSH WORD IN2 



mov a1.IN2 
xor ah, ah 
push ax 



CALL DOSXAMPL 



call DOSXAMPL 
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OS/2 Sample Functions 



The following are sample functions. The code indicated is similar to 
IBM Personal Computer Macro Assembler. Some definitions and 
necessary statements for segments and procedures are left out. 



Function DOSXAIMPL 



This is an example function that retrieves information from a stack. It 
shows entry and exit sequences for a function and how to access the 
parameters. 

push bp 
mov bp,sp 



les bx,[bp+8] ; get the 0 of OUTl 

mov word ptr es:[bx],77 ; put 77 in OUTl 
mov ax,[bp+12] ; put INI 1n ax 



mov bl,[bp+6] ; put IN2 in b1 



mov ax, 17 ; set the return code to 17 

pop bp 

ret (far) 8 ; remove parameters from stack 

; and return 
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HIgh-Level Language Interface Examples 



These are examples of high-level language Interfaces for the "OS/2 
Sample Functions" on page 2-8 and the "Function Calling Sequence 
Example" oh page 2-7. 

IBM Pascal Compller/2'^2: This is ah example of the Interface used 
with the IBM Pascal Compiler/2™. 

Declaration function DOSXAMPL( pjnl : integer; 



IBM Ci2™^. This Is an example of the interface used with the IBM 

C/2™. 



var p_outl : integer; 
p_in2 :char 
): integer; 



Data Declaration 



var p_inl, 

p_outl : integer; 
rc : integer; 
p_in2 :char; 



Invocation 



rc := D0SXAMPL(44,outl,xin2); 



Declaration 



int far pascal DOSXAMPL(); 



Data Declaration 



int_outl; 



int rc; 



char xin2; 



Invocation 



rc = D0SXAMPL(44,(char far *) &outl,xin2); 



2 Pascal Compiler/2 Is a trademark of 

International Business Machines Corporation. 



3 G/2 is a trademark of 

International Business Machines Corporation. 
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OS/2 Compatibility Considerations 



Three levels of Application Programming interface (API) are sup- 
ported by OS/2 to provide different levels of function and 

compatibility: 

• OS/2 dynamic Wnk full-function API for programs that require 
multitasking and memory management function. 

• DOS Family API (subset of OS/2 API) for programs that require 
compatibility with both OS/2 and DOS. 

• DOS interrupt-based API for programs that require only DOS 
compatibility. 

OS/2 Application Environments 

Two application environments are supported by OS/2 for applications: 

• The OS/2 mode 

• The DOS mode 

OS/2 provides two environments for running applications; the DOS 
mode and the OS/2 mode. The DOS mode allows DOS applications to 
run concurrently with OS/2 applications. The OS/2 mode allows mul- 
tiple OS/2 applications (both full-function and family) to run concur- 
rently. 

The 80286 processor provides two hardware modes of operation, real 
mode and protected mode. To support the two application environ- 
ments, OS/2 handles requests for service from both modes. OS/2 
applications run in the protected mode of the processor. 

A DOS application running in the DOS mode runs in both modes, that 
is, the processor switches from real to protected mode and bacl< 
again. For example, ail file requests are handled in protected mode. 
This provides a means of insuring data integrity across multiple 
applications in a multitasking operating system. 
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The following table shows the API support in each environment: 



API 

OS/2 



Family 
DOS 



Environment 
OS/2 DOS 

Yes No 
Yes Yes^ 
No Yes^ 



No 

Yes' 

Yes^ 



DOS 3.3 



Notes: 



1. See the API Functions in Technical Reference, Vol. 2 for Family 
API restrictions. 

2. For DOS API compatibility exceptions in the DOS mode see "DOS 
Mode Exceptions" on page 2-19. 

DOS Family and Full Function API 

The DOS Family API function calls are a "subset" of the full OS/2 API 
function calls. When an application program is written using only the 
DOS Family API function calls, it can be linked to worit with both OS/2 
and DOS 3.3. A family application can also work under TopView. 

In reading the chart that follows, remember: 

• "Family API" (middle column) is a list of the family API functions 
that work in the OS/2 mode, the DOS mode, and DOS 3.3. 

• The "OS/2 Only" column means these function calls work in the 
OS/2 mode only. 

• The combination of both columns is the OS/2 full-function API. 

• The function calls listed in the "Family API" column marked with 
an asterisk (*) are supported, but with restrictions. The 
restrictions are described in the detailed description for each 
affected function call in Technical Reference, Vol. 2 as Family API 
Considerations. 
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Function Type Family APi Subset OS/2 Oniy 

Tasking 

DosC reateTh r ead 

DosCWait 

DosEnterCritSec 

* DosExecPgm 

* DosExit 

DosExitCritSec 

DosExitList 

DosGetlnfoSeg 

DosGetPrty 

DosKillProcess 

DosPtrace 

DosSetPrty 

Asynchronous Notifi- 
cation 

* DosHoldSignal 

* DosSetSigHandler 

Interprocess Commu- 
nication 

DosCloseQueue 

DosCioseSem 

DosCreateQueue 

DosCreateSem 

DosFlagProcess 

DosMal<ePipe 

DosMuxSemWait 

DOsOpenQueue 

DosOpenSem 

DosPeekQueue 

DosPurgeQueue 

DosQueryQueue 

DosReadQueue 

DosResum eTh riBad 

DosSemCiear 

DosSem Request 

DosSemSet 

DosSemSetWait 
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Function Type 



Timer 



Family API Subset 



Memory Management 



Dynamic Linlcing 



DosGetDateTime 
DosSetDateTime 
DosSleep 



* DosAllocSeg 

* DosAllocHuge 

* DosCreateCSAIias 
DosFreeSeg 
DosGetHugeShift 



* DosReailocHuge 

* DosReailocSeg 
DosSubAlloc 
DosSubPree 
DosSubSet 



OS/2 Oniy 

DosSemWait 

DosSuspendThread 

DosWriteQueue 



DosTimerAsync 

DosTimerStart 

DosTimerStop 



DosAllocShrSeg 



DosGetShrSeg 
DosGetSeg 
DosGiveSeg 
DosLockSeg 
DosMem Avail 



DosUnlocl<Seg 

DosFreeModule 

DosGetModHandle 

DosGetModName 

DosGetProcAddr 

DosLoadModule 
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Function Type 

Family API 



Family API Subset 



OS/2 Only 



DosGetMachlneMode 
BadDynLink 



Device Monitors 



Session Management 



Device I/O Services 



DosBeep 

DosDevConfig 

DosDevlOCtI 

DosGetPID 



KbdCharIn 



KbdFlushBuffer 



KbdGetStatus 



DosMonClose 

DosMonOpen 

DosMonRead 

DosMonReg 

DosMonWrite 

DosStartSesslon 
DosStopSession 
DosSelectSession 
DosSetSesslon 



DosCLIAccess 



DosPFSActivate 

DosPFSCIoseUser 

DosPFSInIt 

DosPFSQueryAct 

DosPFSVerifyFont 

DosPhyslcalDisk 

Dos Port Access 

DosSendSlgnal 

KbdDeReglster 

KbdClose 

KbdFreeFocus 

KbdGetCp 

KbdGetFocus 
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Function Type 



Family API Subset 

* KbdPeek 



KbdSetStatus 
KbdStringIn 



OS/2 Only 

KbdOpen 

KbdRegister 
KbdSetCp 
KbdSetCustXt 
KbdSetFgnd 



KbdSynch 

KbdXIate 

MouClose 

MouDeRegister 

MouDrawPtr 

MouFlushQue 

MouGetDevStatus 

MouGetEventMask 

MouGetNumButtons 

MouGetN u m M i ckeys 

MouGetNumQueEl 

MouGetPtrPos 

MouGetPtrShape 

MouGetScaleFact 

MoulnitReal 

MouOpen 

MouReadEventQue 

MouRegister 

MouRemovePtr 

MouSetDevStatus 

MouSetEventMask 

MouSetPtrPos 

MouSetPtrShape 

MouSetScaleFact 

MouSynch 

VioDeRegister 

VioEndPopUp 

VioGetAnsi 

VioGetBuf 



2-15 



Function Type Family API Subset OS/2 Only 

VioGetCp 

VioGetConfig 

VioGetCurPos 

VioGetCurType 

VioGetFont 

VioGetMode 

VioGetPhysBuf 

VioGetState 

VioModeUndo 

VioModeWalt 

VioPopUp 

VioPrtSc 

VioPrtScToggle 

VioReadCellStr 
VioReadCharStr 

VioRegister 

VioSavRedrawUndo 

VioSavRedrawWait 

* VioScrLock 
VioScrollDn 
VIoScrollUp 
VioScrollLf 
VIoScrolIRt 

* VIoScrUnLock 

VioSetAnsi 
VioSetCp 

VIoSetCurPos 

VioSetCurType 

VIoSetFont 

VioSetMode 

VioSetState 

VIoShowBuf 

VioWrtCellStr 

VioWrtCharStr 

VioWrtCharStrAtt 

VioWrtNAttr 

VioWrtNCell 
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Function Type 



Family API Subset 

VioWrtNChar 
VioWrtTTY 



OS/2 Only 



File I/O 

DosBuf Reset 

DosChDir 

DosChgFllePtr 

DosClose 

DosDelete 

DosDupHandle 

* DosFlleLocks 

* DosFlndClose 

* DosFindFlrst 

* DosFindNext 
DosMkDir 
DosMove 
DosNewSIze 

* DosOpen 
DosQCurDir 
DosOCurDisk 

* DosOFHandState 
DosQFIIelnfo 
DosQFileMode 
DosQFslnfo 
DosQHandType 
DosQVerify 
DosRead 

DosRmDir 



DosSelectDisk 
* DosSetFHandState 
DosSetFllelnfo 
DosSetFileMode 
DosSetFsinfo 



DosReadAsync 

DosScanEnv 
DosSearchPath 

DosSetMaxFH 



Function Type Family API Subset OS/2 Only 

DosSetVerify 
DosWrite 

DosWriteAsync 

Errors and Exceptions 

DosErrCiass 

* DosError 

* DosSetVec 

Messages 

* DosGetMessage 
DoslnsMessage 
DosPutMessage 

Trace 

Program Startup 

DosGetEnv 
DosGetVersion 

Code Page Support 

* DosGetCp 
DosSetCp 

DosSetProcCp 

Country Support 

DosCaseMap 
DosGetCollate 

* DosGetCtrylnfo 
DosGetDBCSEv 

Note: BadDynLink is a call generated internally by the BIND utility. 
BadDynLink is for dynamic link calls that are unresolved in DOS 3.3 
and yet valid in the OS/2 mode. This allows applications to have a 
set of function calls available in the OS/2 mode that are not available 
in DOS 3.3. The DosGetMachineMode call can be used in the applica- 
tion to determine at run-time whether a call is appropriate. 

If a routine is called in DOS 3.3 that is not valid for the DOS mode, the 
BadDynLink routine aborts the application. 
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DOS Mode Exceptions 

In the DOS mode, all the functions that are supported In DOS 3.3 with 
SHARE installed are supported in OS/2 with some exceptions. 

Note: Undocumented DOS 3.3 function calls are not supported. 

DOS 3.3 Network Function Calls 

No DOS 3.3 Network functions calls are supported. 

Version Number 

The version number returned to an application in response to 
the version call is 10.0, instead of the displayed version number 
1.0. 

Background Freezing 

When the process (the DOS mode application) is in a back- 
ground session, the DOS mode is frozen. The process receives 
no task-time CPU service and no interrupts. One effect is that 
an application that is tracking the time of day by counting clock 
tics will have an incorrect count when it returns to the fore- 
ground. 

Hooking Hardware Interrupts 

DOS mode applications may hook any hardware interrupt vector 
unless the interrupt is already owned by an OS/2 device driver 
in which case the DOS mode application is terminated. If the 
keyboard interrupt is hooked by an application, it is shared 
between the OS/2 device driver and the DOS mode. 

Direct Device Manipulation 

There are restrictions on the devices DOS mode applications 
may directly manipulate: 

• 8042 Keyboard Interrupt Controller - DOS mode applications 
may not reprogram the 8042 keyboard interrupt controller. 

• 8253 Clock/Timer chip - DOS mode applications may repro- 
gram this at will. 

• 8259 Interrupt controller - DOS mode applications may not 
reprogram the 8259 interrupt controller. 

• Disk Controller - DOS mode applications may not repro- 
gram the disk control I er(s), although they may have direct 
access via INT13, INT25 and INT26. However, INT26 is not 
allowed to non-removable media and for INT 13H, only 
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functions 01 (read status), 02 (read sectors), OA (read long), 
and 15 (read DASp type) are allowed to non-removable 

nnedia. 

• DMA Controller(s) - DOS mode applications may not repro- 
gram the DMA ports. 

• COM/P^raliel Port - DOS mode applications should not use 
COM ports that are being used by OS/2 mode applications, 
or by the Print Spooler utility. 

Using a port in the DOS mode removes it from availability in 
the OS/2 mode. If the OS/2 mode uses one of these ports, it 
is unavailable to the DOS mode. Applications that perform 
I/O directly to the serial and parallel ports without checking 
the BIOS presence indicators can interfere with the opera- 
tion of these devices by the OS/2 bimodal device drivers. 

DOS mode applications will fail if they attempt to access the 
BIOS 40: data area when the Asynchronous device driver is 
loaded if SETCOM40 has not been run. AUX is no longer 
supported as an alias for C0M1 . 

Device Drivers 

See "Compatibility with Previous-Level Device Drivers" on 
page 7-29. 

DOS Software Interrupts 

See "DOS Execution Environment Software Interrupt Support" 
on page 7-31 for exceptions. 

DOS Commands 

See "DOS Commands Compatibility Exceptions" in the OS/2 
User's Reference. 
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Chapter 3. Memory Management 



Memory management under OS/2 using the Protected Virtual- 
Address mode of the 80286 permits applications to allocate more 
memory than could fit in the 640K physical limit that existed in pre- 
vious versions of DOS. In addition, if the user enables swapping, 
OS/2 allows one or more applications to allocate more memory than 
is physically available in the system. 



Use of the Segmentation Hardware 

A feature of OS/2 is utilization of memory beyond the 640K limit 
through comprehensive memory management functions. These func- 
tions fully exploit the segmentation capability of the hardware in the 
protected address mode of the 80286. Use of these functions allows 
full utilization of the processor architectural storage limit of 16Mb. 

Applications written with these memory management functions will 
be able to use more memory than the 640Kb limit of previous DOS 
versions. When memory becomes full, OS/2 maintains the most 
active segments in storage. Inactive segments (least recently used 
segments) are swapped to disk. Active segments are loaded into 
storage as needed. 

These new OS/2 mode functions permit you to concurrently execute 
more programs than will fit in memory. Any single program and its 
data can be larger than real memory. 



3-1 



The new functions provided allow a program to: 

• Allocate a large number of data segments; each may be up to 
64Kb. 

• Allocate multiple memory segments of the maximum segment 
size (64Kb). 

• Keep each segment private or share it with other programs. 

• Pacl^age an application so that the linkage to library routines or 
infrequently used routines is not made until run time. 

• Implement an application as a number of distinct CALLable seg- 
ments with OS/2 providing load on demand. 

• Explicitly load programs If desired. 

The Protection Features off the Ring Structure 

The OS/2 protection model takes advantage of the 80286 ring pro- 
tection architecture to protect the integrity of applications. 

The protection levels used by OS/2 for program execution are: 

• Applications run at protection level 3. 

• Special purpose routines (other than general device drivers) 
requiring I/O privilege execute at protection level 2. 

• The kernel and device drivers run at protection level 0. 
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The following diagram shows the application perspective of the pro- 
tection model provided by OS/2: 
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For a module to be loaded at protection level 2, the CONFIG.SYS 
IOPL=yes command must indicate this is to be allowed. Protection 
level 2 modules cannot use dynamic VinW, and cannot make OS/2 func- 
tion calls. 
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The OS/2 protection model uses the 80286 ring protection architecture 
to insure that for each level in the hierarchy, only programs at that 
level, or a more privileged level, can access data at that level. For 
example: 

• An application has access only to Its own data at level 3. 

• A level 2 I/O module has access to its clients' application data at 
level 3. 

• The kernel and device drivers have access to data at all levels. 



OS/2 Mode Memory Management 

Protect mode memory management enables an OS/2 mode applica- 
tion to use large real memory beyond the 640Kb boundary imposed 
by previous versions of DOS. Memory management is supported with 
both memory compaction and segment swapping. 

In protect mode there is one Local Descriptor Table (LDT) per 
process for all threads running under that process. Each process has 
its own distinct address space, mapped by an LDT and the Global 
InfoSeg. The LDT provides a per process private address space 
while the Global InfoSeg provides addressability for system-wide 
data and programs which are shared among all processes. 

Together these tables provide a virtual address space of 1Gb. 
However, the available virtual address space is limited by the avail- 
able disk storage space. The LDT and Global InfoSeg provide a 
mapping from this 1Gb virtual address space to the 16Mb (maximum) 
physical address space of the 80286. OS/2 dynamic link routines 
have LDT, as opposed to Global InfoSeg, descriptors. Reference 
"Dynamic Linking" on page 4-26 for more information on dynamic 
link routines. 
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The following Is a diagram of the segment swapping, protected 
memory management of OS/2. 
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The features of protect mode memory management support include: 

• Storage over-commitment - the amount of storage allocated at 
any instant for data and code segments can be greater than the 
amount of real memory available. 

• Segment discard - real memory occupied by code segments that 
are still in the address space of an application (though not cur- 
rently in use) can be reclaimed by discarding the segment. When 
the discarded segment is later referenced, a fresh copy is read 
from the .EXE fjle, whereas swapping restores from a swap area. 

• Segment motion (memory compaction) - t>ecause segments are 
variable length, real memory is subject to external fragmentation. 
Holes of deallocated real memory, each of which is insufficient in 
size to satisfy a request for memory, but which together would be 
sufficient, are united in order to satisfy the request. 
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• Protection - applications only have addressability to memory seg- 
ments specifically authorized to them by the system. The OS/2 
system and each individual application are protected from access 
by other applications. 



Real Memory Map (Protect mode only) 
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Note the x Kb and y Kb boundaries. These are movable boundaries 
separating the fixed and movable regions of memory. The actual 
location of these boundaries will vary depending on the system load 
and the amount of real memory installed. 



Real Mode Memory Map 

A real mode system allows execution of a single DOS mode applica- 
tion in addition to new OS/2 mode applications. 

A DOS mode application executes only below 1Mb (in fact, because of 
the reserved ROM and video buffer space, only below 640Kb) while 
an OS/2 mode application may execute at any address. 
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The following diagram shows the memory layout for an OS/2 system 
running both OS/2 mode applications and a single DOS mode applica- 
tion. OS/2 mode code and data segments are loaded above a 
boundary set by the RMSIZE= command In CONFIG.SYS. The fol- 
lowing diagram assumes the boundary is set at 640K bytes. 



Real Memory 



New Application 



Code and Data Segments 



I/O Segments (Long Term) 
OS/2 



OS/2 



ROM and Video Buffers 



Single 
"Old" Application 



OS/2 SYSTEM 



Movable, 

Swappable 
or 

Non-swappable 



Fixed 



Variable size 



Note the x Kb and y Kb boundaries. As in the previous Real Memory 
Map, these are movable boundaries separating the fixed and 
movable regions of memory. The actual location of these boundaries 
will vary over time, depending on the system load and the amount of 
real RAM installed. 

Note the z Kb boundary. This defines the logical end of memory for 
the DOS 3.3 application and may vary up to the 640Kb limit. Protect 
mode memory is above this boundary. 
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Memory Management Function Call Summary 



The following memory management Interfaces are supported: (For a 
detailed description of these function calls refer to Technical Refer- 
ence, Vol. 2.) 

DosAllocHuge Allocates multiple memory segments of the 
maximum segment size (64Kb). 

DpsAllocSeg Allocates a segment of memory to the requesting 
process. 

DosAllocShrSeg Allocates a shared memory segment. 

DosCreateCSAIias Creates a code segment alias descriptor for a 
data segment passed as input. 



DosFreeSeg 
DosGetHugeShift 

DosGetSeg 
DosGetShrSeg 

DosGlveS^g 
DosLockSeg 
DosMemAvall 

DosRealiocHuge 

DosRealjocSeg 
DosUnloQkSeg 



Deallocates a segment. 

Returns a shift count. The shift count is used in 
deriving the selectors to address memory allo- 
cated with DosAllocHuge. 

Gets access to a shared memory segment. 

Allows a process to access a shared memory 
segment previously allocated by another 
process. 

Gives a memory segment to another process. 

Locks a discardable segment In memory. 

Returns the size of the largest block of free 
memory. 

Changes the size of memory allocated by 
DosAllocHuge. 

Changes the size of a segment already allocated. 
Unlpcks a discardable segment. 
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Memory Suballocation Package (MSP) 



In addition to the extensive segment swapping memory management 
functions described above, OS/2 includes a higii-performance mech- 
anism for suballocation within a segment (small model) similar to a 
linked-list of storage descriptors. 

The OS/2 Memory Suballocation Package (MSP) is a set of intraseg- 
ment memory allocation dynamic link routines. The functions support 
memory suballocation within a segment. The memory suballocation 
dynamic link routines are packaged within the dynamic link module 
D0SCALL1.DLL. External references to memory suballocation 
dynamic link routines are resolved at link time. 



Memory Suballocation Example 

Following Is an example of an application making memory suballo- 
cation requests. At the top Is a succession of allocate requests which 
deplete the FREE storage within the segment. 
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The application may now begin freeing the storage as it is no longer 
needed. Adjacent free blocl^s are combined: 
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MSP Function Call Summary 

The following MSP interfaces are supported: 

(For a detailed description of these function calls refer to 

Technical Reference, Vol. 2.) 

DosSubSet Used either to initialize a segment for sub- 

allocation or to change the size of a subalio- 
cation segment previously initialized. 

DosSubAlloc Allocates memory from a segment previously 
allocated by DosAllocSeg or Dos AllocShrSeg 
and initialized by DosSubSet. 

DosSubFree Frees memory previously allocated by 

DosSubAlloc. 
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System Extensions 



OS/2 provides a base on which application developers can construct 
solutions to more complex applications. To an application, these sol- 
utions typically appear as an extension of the operating system (for 
example, Presentation Manager); and they require many of the same 
capabilities as the kernel, such as protection, data isolation and 
sharing, and an efficient means of invocation. The design of OS/2 
provides functions that allow the extension author to obtain these 
capabilities easily. 

The system extension provides a callable routine which is its applica- 
tion interface. The actual connection from the application program to 
the system extension is made at run time (see "Dynamic Linking" on 
page 2-2 and "Dynamic Linking" on page 4-26 for details on this 
linkage.) When called, the extension routine either performs the 
request directly or passes the request on to a separate process which 
performs the request asynchronously. System extensions are imple- 
mented as dynamic link modules. 

The determination of processing directly or under a separate process 
must be made based on the data isolation and performance charac- 
teristics of the solution being offered. 
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The following diagram shows the invocation of a system extension via 
the run time dynamic llnldng. 
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For processing of the request under a separate process, interprocess 
communications techniques may be implemented using semaphores, 
queues, signals, or shared memory. 

The above diagram also demonstrates the program execution flow 
and the data handling aspects of providing a system extension as a 
callable routine. Note that the extension may allocate data exclusive 
to each of its clients. 
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Chapter 4. Process Control 



The process control functions of OS/2 are: 

• Timer Services 

• Multitaslcing 

• Interprocess Communication (IPC) 

• Asynchronous Notification 

• Program Execution Control 

• Errors and Exceptions 

• OS/2 Message Functions 



Timer Services 

These services are related to time of day and intervals of time. They 
provide the full range of time primitives for implementing timer-based 
applications. 

Timer Mlanagement 

In OS/2* all time-related functions are based on a periodically inter- 
rupting time source. The timer operates with a frequency of approxi- 
mately 32 hertz. This rate is sufficient for most applications, but you 
are limited to a time interval with a precision of less than 50 millisec- 
onds. 

Time/Date 

DosGetDateTime and DosSetDateTime are the function calls that get 
and set the system date and time. (For a detailed description of these 
function calls refer to Technical Reference, Vol. 2.) 
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Timer Intervals 



In addition to tlie Date and Time functions, OS/2 provides tlie fol- 
lowing time-interval functions: 

• Asynchronous intervals - the system notifies a task that a period 
of time has elapsed. 

• Regularly occurring intervals - the system continuously notifies a 
task that a designated period of time has elapsed. 

• Sleep for a period of time - a task can delay its execution for a 
certain period of time. 

The timer interval functions allow specification of the time interval in 
milliseconds; however to reduce system overhead, the actual resol- 
ution is typically on the order of 50 milliseconds. 

The timing functions are only accurate to within one or two clock 
ticks. The application can perceive that the time elapsed is longer 
than specified because of delays in getting the application resumed. 
All time values are in milliseconds and are rounded up to the next 
clock tick. The clock tick duration can be determined by using the 
DosGetlnfoSeg function and examining the timer interval field in the 
Global InfoSeg. 

If it is necessary for an application to know the time elapsed while 
waiting for a timer, a comparison can be made of the milliseconds 
field (in the Global InfoSeg) before the wait began and the millisec- 
onds field after the application resumed execution. This technique is 
accurate to within one or two clock ticks. The value in the millisec- 
onds field will roll over every few weeks. If the application sus- 
pended prior to a rollover and awoke after a rollover then the elapsed 
time calculation may need to take that into account. 

When interrupts are disabled for periods longer than the clock tick 
interval, the milliseconds field can lose time. However, the time of 
day (hours, minutes, seconds), time in seconds since 1-1-70, and the 
date will remain accurate. When interrupts must be disabled for a 
long period, the elapsed time should be computed from seconds, 
rather than milliseconds. 
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Timer Services Function Call Summary 



For function call details, refer to Technical Reference, Vol. 2. 



The timer services function calls provided are summarized as 
follows: 

DosGetDateTime Get the system date and time 
DosSetDateTlme Set the system date and time 



DosSleep 

DosTimerAsync 

DosTimerStart 

DosTlmerStop 



Synchronous pause (wait or sleep) for interval of 
time 

Start asynchronous timer, one shot 

Start interval timer, asynchronous, continuous 

Stop interval or asynchronous timer 



Multitasking 

Multitasking is an integral part of OS/2. A priority-based, time-slicing 
scheduler is provided with special consideration for applications with 
time critical response requirements. 

The functions provided to a multitasking application developer 
include the ability to: 

• Initiate and terminate other processes 

• Vary a process' dispatch priority 

• Execute programs as separate processes 

• Coordinate execution among several processes 

• Communicate between several processes. 

Many of these functions are also available for multiple execution 
threads within a single process. 

The multitasking features of OS/2 allow a user to operate several 
applications concurrently. For most purposes, each application 
appears to run in a separate projected computer by itself and can be 
designed and coded in much the same manner as under the current 
DOS. This case of multiple concurrent applications is the simplest 
form of multitasking. In this instance, each application's execution is 
managed under a process and one thread of execution. 
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For more complex application requirements, an application can be 
designed such that its functions are divided among a collection of 
cooperatinig processes (or threads). 

Threads are dispatched for execution on a priority basis with a time- 
slicing scheduler being provided to ensure threads of equal priority 
receive an equal opportunity to execute. For applications with time 
critical response requireinents, special mechanisms (such as 
DosEnterCritSec and DosExitCritSec) are provided to ensure their 
successful operation. 

Tasking (Processes and Threads) 

This section describes those functions that are provided to initiate 
and terminate processes, to vary process priority, and to execute 
other programs as separate processes. 

The section "Interprocess Communication (IPC)" on page 4-9 
describes those functions that provide coordination and communi- 
cation between processes. 

Definitions 

Process An instance of program execution. Includes at least one 
thread and ownership of resources defined or used by the 
program. 

Tliread A unit of execution within a process. A thread is the dis- 
patched unit. 

A process is that identifiable entity which represents an executing 
program and the resources in use by that program. Only a process 
can own resources; a thread can only access resources on behalf of 
its parent process. 

The thread is the dispatched unit within a process. A thread is not 
identifiable outside its parent process. 
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Where necessary, various sections of this bool< use terms such as 
current thread, waiting thread, or parent thread. This terminology is 
meant to clarify discussing one thread of a process, rather than the 
process itself. 

An application can be designed as several distinct processes or as 
multiple threads within a single process. Consider the following: 

• The creation and termination of a thread is very fast while the 
creation of a process is relatively slow. 

• Sharing of data and resources between threads is natural. 
Sharing between processes requires special considerations. 

• The creation of a process is costly to system memory. 

• If the problem can be best solved by multitasl<ing entities with a 
high degree of independence, multiple processes is the proper 
choice. 

• Several independent processes may also be the best choice for 
applications in which the independence or function of the process 
model is required. This is particularly true when the various pro- 
grams of the application are tightly coupled with respect to inter- 
process communication or fixed, shared data areas. 

• Multiple threads is the better choice if the concurrent execution 
entities are started for only a short period of time as the overhead 
to start and end a thread is much less than for a process. 

• A thread is also more suitable for problems in which multiple 
executions are needed, yet where each execution need not be 
externally identifiable and does not require distinct or separate 
resources. 
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The diagram below shows the process structure when the user has 
started three applications: an editor, a communications handler, and 
a data base manager. Because these are independent applications, 
they have no knowledge of one another. The fact that they can share 
a physical disk on which their individual Disk Files are located is 
known and managed only by OS/2. 
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For a solution to an application where multiple asynchronous exe- 
cution threads are needed, the following diagram demonstrates how 
the various threads might operate, each using different devices to 
accomplish a portion of the overall solution. 



Multiple Threads within a Process Diagram 
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Resource Management 

OS/2 provides resource management and tracks ownership at the 
process level. The resources which a process can own, or be 
granted controlled access to, are: 

• Files (and devices If opened at that level) 

• Memory 

• Pipes 

• Queues 

• System semaphores 

When a process terminates, any of the above resources which it does 
not explicitly close or release is released automatically. 



Tasking Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 



The tasking function calls are summarized as follows: 



DosCreateThread 

DosCwait 

DosEnterCritSec 

DosExecPgm 

DosExit 

DosExitCritSec 

DosGetinfoSeg 

DosGetPrty 

DosKIIIProcess 

DosSetPrty 



Start a thread of execution within a process. 

Wait for a child process's termination. 

Enter critical section of execution. 

Execute a program as a new process. 

Exit the current thread or process. 

Exit critical section of execution. 

Get addresses of system variables segments. 

Get a process's (or thread's) priority. 

Terminate another process. 

Set a process's (or thread's) priority. 



4-8 



Interprocess Communication (IPC) 

OS/2 provides several methods for interprocess communication: 

• Signals 

• Messages 

- Pipes 

- Queues 

• Semaphores 

- RAM semaphores 

- System semaphores 

• Shared memory 



Pipes, queues, and semaphores are created by the applications. 
They are identified by handles, or addresses that are passed among 
the interested processes as necessary. 



The semaphore support provides serialization, or signalling, by 
means of RAM semaphores and system semaphores: 

• RAM semaphores are a high-performance mechanism best used 
between the threads within a process. 

• System semaphores are a high-function mechanism particularly 
suited for use between processes. 

To ease the task of sharing resources between programs, OS/2 
extends the standardized naming conventions of the file system to 
queues, system semaphores, and shared memory. This ensures ref- 
erences to the same name are resolved to the same resource. 
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Communication via Signals 

Communication via signals is used to allow one process to set an 
external event flag to another process. The target process must use 
DosSetSigHandler to inform OS/2 that it wishes to intercept any of 
three flags. Another process then can issue a DosFlagProcess indi- 
cating which of the flags to signal. The target process will receive 
control at the signal handler it has defined for that signal. 

Communication via IVIessages 

Two facilities provide for interprocess communication via 
messages - pipes and queues. 

Pipes 

Pipes are an IPC mechanism based on the file I/O concept. Pipes are 
a technique by which two related processes can communicate as if 
they were doing file I/O. In fact, a program which inherits a pipe 
handle cannot distinguish if its I/O requests to that handle are to a file 
or pipe. 

For communicating via pipes, the standard OS/2 read and write func- 
tions are used. Pipe support Is provided only for applications in 
which the pipe participants are a closely related group of processes. 
The functions provided are in the DosMakePipe function call. 

The storage required, or available, for a pipe I/O request to be per- 
formed can be a consideration. Pipes are effectively fixed length in 
nature. The most any pipe can hold is 64Kb at any one time. If a pipe 
is full, further write requests will block until sufficient data is removed 
from the pipe. 
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For example, with C0MMAND.COM a user issues a DIR command, 
piping DIR's output to SORT. This gives a sorted directory listing. 



Piping Output of One Program to Another: The following diagram 
depicts how information is piped from one program to another: 
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OS/2 keeps track of the data and free space in the pipe with the Next 
IN and Next OUT pointers. When the pipe is full, the next write by the 
DIR process waits until SORT has removed enough data to make 
room for the new message. 

Pipes can also be used as a form of a fixed length first-in-first-out 
(FIFO) circular queue providing communication between processes. 
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Communicating witii a Pipe 



The following diagram depicts the use of a pipe to pass data to a 
server process X from three child processes A, B, and C. The 
sending processes send data independently of one another. Process 
X removes data from the pipe in the order in which it arrived. 
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Comparing Pipes witii Fiies: 

• Similarities 

- Data is communicated to pipes by the standard DosRead and 
DosWrite function calls. 

- Pipes are closed by the standard DosClose function call. 

• Differences 

- Pipes are created by DosMakePipe rather than one of the file 
system create requests. 

- Pipes need not be opened before being accessed, only the 
DosMakePipe is necessary. 

- Pipes are implemented via an Internal storage buffer mech- 
anism rather than having their data maintained on disk. 
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- When writing to a file, the requesting thread is blocked only 
while doing file I/O. When writing to a pipe, the requesting 
thread will block if the pipe reader allows the pipe to fill up. 

- Writing to a pipe is not interspersed. No other thread can 
write to that pipe until the write in progress is completed. 
Any thread that attempts to write to the pipe is blocked. 

- Reading data from a pipe removes that data from the pipe. 
Subsequent reading will not find that data. 

Pipes are inherited in the same manner as files. A using process typ- 
ically creates a pipe, then starts a child process (which inherits the 
pipe handles) and communicates to the child process with the pipe 
handles. 

Queues 

For more sophisticated applications, queues provide a more powerful 
mechanism for interprocess communication of data between proc- 
esses. 

Communicating witti a Queue 

The following diagram shows a queue passing data to a server 
process Y from three child processes D, E, and F. 
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As with pipes, the sending processes can send data independently of 
one another. However, unique to queues, outstanding elements can 
be ordered by priority or by arrival order, first-in first-out (FIFO) or 
last-in first-out (LIFO). Also, process Y can examine each element in 
the queue and remove them whenever, and in any order, desired. 

A feature of queues compared to pipes is that queues have a per- 
formance advantage because the data is not copied in queues, but is 
passed In a shared segment. Also, there is virtually no size limita- 
tion for the messages themselves. While the total message text a 
pipe can contain is 64Kb, queues can contain very large amounts of 
data. This is because each message is a unique block of storage and 
the aggregate of all messages can be dispersed across the entire 
machine. 

Comparing Pipes and Queues 

Queues are similar to pipes, with the following exceptions: 

• Pipes use the file system interface (close, read, write). Queues 
have their own special calls. 

• Pipes are data-stream oriented; queues contain message 
packets. 

• Pipes are FIFO; queue messages can be ordered FIFO, LIFO, or 
by priority and can be accessed in random order. 

• Data in queues can be purged. 

• Queue data is not copied; the shared segment containing the data 
must be made accessible to the recipient. 

• There can be multiple writers into a queue, but only one 
reader/owner. Multiple readers can be realized by means of mul- 
tiple threads within the process which owns a queue. 

• A count of the outstanding queue messages can be supplied to 
any process which has access to a queue. 

• Queues are variable length; however, the maximum number of 
elements which can be placed in a single queue is no greater 
than 3260. 

Like pipes, queues can be blocked on. 
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Pipes are a technique used by two processes to communicate as if 
tliey were doing file I/O. In fact, a program which lists a file can have 
its input or output specified as being a pipe and the program would 
operate without change. The pipe support would ensure that all data 
read or written by the program went to a pipe rather than to a file or a 
printer. 

Programs using queues must be designed and coded with the con- 
cepts and function calls defined by queuing. These calls are not like 
the file I/O calls, and the processing of data is completely different 
from pipes. 

Queues are more efficient than pipes because, only a pointer to the 
data is passed. 



The storage required, or available, for the IPC to be performed is 
often a consideration. Pipes are fixed in length (not over 64Kb); while 
queues can be of relatively unbounded length because queue mes- 
sages do not need to be contained in one segment. 

The application designer must take into account all these factors bal- 
ancing the performance requirements against the storage use char- 
acteristics of each solution. 



Queue Function Calls 



For function call details, refer to Technical Reference, Vol. 2. 



The queue function calls are summarized as follows: 



DosCloseQueue 

DosCreateQueue 

DosOpenQueue 

DosPeekQueue 

DosPurgeQueue 

DosQueryQueue 

DosReadQueue 

DosWrlteQueue 



Close a Queue 
Create a Queue 
Open a Queue 

Get an element from queue, but do not remove it 

Purge all entries from a queue 

Find how many elements are in queue 

Get an element from a queue and remove it 

Add an element to a queue 
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Managing Queues 

This section is an aid to application programmers who are imple- 
menting more complex server environments with OS/2 queuing as the 
means of interface between processes. 

In these environments, it may be advisable to provide a dynamic link 
interface routine which fields application program requests in a lan- 
guage consistent with the server's other calls and translates the 
requests Into the appropriate OS/2 queuing and memory manage- 
ment calls. 

For any of the techniques described here, the memory subal location 
functions (DosSubAlloc, DosSubFree, and DosSubSet) should be used 
to allocate or free any message storage required. 

The Segment for Data Storage 

The OS/2 memory protection features provide total isolation between 
processes with memory being shared only when explicitly requested 
either by the shared memory function calls DosAllocShrSeg and 
DosGetShrSeg or by DosAllocSeg and DosGlveSeg or by DosGetSeg. 

When using the OS/2 queuing functions, the two processes involved 
In the queuing conversation must each have addressability to the 
data that is communicated. (The queuing support provides the offset 
and length of the data, but not message copy facilities.) 

Managing Data Storage Examples 

Several techniques can be used to manage the data storage required 
for the message that is transmitted, depending on the requirements of 
the particular application. For example: 

• For a solution which involves tightly coupled processes communi- 
cating with small messages, or at low data rates, manage the 
message storage in a single shared segment. 

The name for this segment can be established by mutual agree- 
ment among the parties involved or, for simplicity, the name 
chosen for this segment could be the same as that chosen for the 
queue. 
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The biggest disadvantage of this solution is the limit imposed by 
the single 64Kb segment size available for data elements; that is, 
64Kb is the limit that can be devoted to message storage. This 
may not be a problem if the server process is never busy for a 
long period of time or if only short messages are being sent. But, 
the 64Kb limit may not be acceptable for long messages or when 
the server process is unable to keep up with requests from 
several clients. Remember, for this example, the 64Kb limit 
applies to the sum of all messages for all client processes. 

• For a more complex server-client implementation, where poten- 
tially many client processes are driving a server, use a queue- 
driven server that provides support for several processes. 

For this example, assume the server provides either a single 
queue for all clients or a separate queue for each client. 

A table could be kept with each entry being composed of: 

- The Process ID (PID) 

- Shared memory segment name 

- Shared memory handle. 

On any CALL, the server need only obtain the currently active 
PID, scan its table looking for that PID and: 

- If found, get the storage handle to be used for this process. 

- If not found, the storage segment has not been created. As 
this must be the first request from this process, the shared 
segment must be created and a table entry setup for this 
process. 

When the server close function is received, the server must 
remove this process entry from the table. 

• You could also allocate the data segment with DosAllocSeg and 
use DosGiveSeg to pass addressability to the server. This 
method allows each message to be any size up to the 64Kb limit. 

For this technique, the following steps can be used: 

- When issuing DosOpenQueue, the process ID of the queue 
owner is saved. 

- The queue element segment is allocated, via DosAllocSeg, 
specifying the segment is to be shared. 
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- DosGiveSeg is used to pass addressability to the segment 
from tlie client to the server. 

- When a request is to be made, DosWriteQueue is issued ref- 
erencing this segment by providing the Recipient SegHandle 
(returned from DosGiveSeg) in the DataBuffer field. 

When the client completes its queue requests or terminates, the 
server should Issue a DosFreeSeg to release the segment. 

Queue Element Copy Function 

A highly efficient element copy function can be implemented by 
means of the DosGiveSeg technique described above. As the client 
allocates the buffer and gives it to the server, there is no added per- 
formance cost required to subsequently make a copy of the data from 
the client's buffer to the server's buffer. 

Queue Element Delete Function 

Some server applications can require the ability to delete individual 
elements from a queue. For example, on discovering that a client 
process has terminated. It may be necessary to delete all remaining 
elements which are from that process. 

This can be accomplished by setting up a loop similar to the 
following: 

Do until end_of_queue 
DosPeekQueue NoWait 

If Have Element AND element's PID = PID of interest 
Then 

DosReadQueue Element Peeked above 

Enddo 
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Coordinating Execution Among Severai Tiireads 

In a multitasking application environment, OS/2 functions allow proc- 
esses to exercise some control over other processes and/or threads 
within their own process. The functions provided include: 

• Semaphores (RAM-based and file-system-based) 

• Starting and stopping a thread's execution 

Semaphores 

Semaphore functions allow multiple processes (or threads) to control 
access to serially reusable resources within the same process. 
There are two types of semaphores supported: RAM semaphores and 
system semaphores. 

RAIM Semaphores 

RAM Semaphores are defined by the requesting program allo- 
cating a double word of storage and using the address in the 
semaphore calls provided below. RAM semaphores are a 
minimal-function mechanism with OS/2 performing no resource 
management services such as freeing when the owner termi- 
nates. 

RAM semaphores are a high-performance mechanism that 
require using processes to have shared access to the same 
area of memory in which the RAM semaphore is defined. The 
affected processes define the semaphore by convention (mutual 
agreement) as a particular double word in some shared storage 
area. 

RAM semaphores are best suited for signaling. They cannot be 
used to control access to resources reliably. 

System Semaphores 

System Semaphores are defined by OS/2 in response to a 
create-semaphore function call. Once created, they can be 
accessed by separate processes, and OS/2 provides full 
resource management, including freeing and notification when 
the owner terminates. 

System semaphores are a full-function mechanism, providing 
control between any process and thread with OS/2 managing 
the storage for the semaphore data structure. System 
semaphores are defined within the file-system name space as a 
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pseudo file instead of a RAM location. The semaphore is a 
pseudo file in that its name takes the form of a file in the subdi- 
rectory SEM, although this subdirectory does not actually exist; 
system semaphores and their names are kept in memory. 

Comparison of RAM and System Semaphores 

When discussing semaphores, the terms owned, unowned, set, or 
clear are used to describe the state of a semaphore at a particular 
time. The concept of ownership applies only to system semaphores 
which are created with exclusive ownership indicated. When a 
semaphore is owned, it is an error for a thread other than the owner 
to try to modify that semaphore. 

The handip for RAM semaphores is the address of the double word of 
storage allocated. If the address of the RAM semaphore is invalid, 
the system will terminate the process with a general protection fault. 

• System semaphores are more flexible and easier to use than 
RAM semaphores because: 

- They can be used by processes which do not share memory. 

- Their ownership Is relinquished when the owner terminates. 

- They provide more function. 

• RAM semaphores offer a slight performance advantage over 
system semaphores because the handle used to refer to them is 
actually the address of the semaphore. The handle of a system 
semaphore must be translated to the memory address of the 
semaphore data structure. 

• RAM semaphores should not be used between processes to 
control access to a serially reusable resource because it is not 
possible to relinquish the semaphore should the owner end 
abnormally. In the case of system semaphores, should the owner 
end, OS/2 will release the semaphore and notjfy the next thread 
which gets the semaphore that the owner ended while holding the 
semaphore. 

Note: RAM semaphores can be used between cooperating proc- 
esses. DosExitList can be used, for instance, to write into a 
shared memory location to inform a process using a RAM 
semaphore that the semaphore owner has ended abnormally. 
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RAM Semaphore Diagram 



The following diagram depicts the use of DosSemRequest and 
DosSemClear for serializing access to a resource. Only a single 
thread can enter the semaphore at a time. The effect is that all other 
threads are locked-out from use of the serially reusable resource 
until the entering thread leaves the semaphore. 
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General Semaphore Function Calls 



The function calls provided for controlling access to a serially reus- 
able resource (via either RAM or system semaphores) are: 



DosSemClear 
DosSemRequest 



Clear a semaphore. 
Obtain a semaphore. 



Signalling via Semaphore Function Calls 



In addition to the resource control semaphore function calls 
described previously, OS/2 provides three function calls to signal that 
an event has occurred between threads/processes: DosSemSet, 
DosSemSetWait, and Dos MuxSem Wait. These function calls can be 
used in combination with the DosSemClear and DosSemSet function 
calls to awaken a blocked thread whenever a semaphore is cleared, 
rather than when it is no longer owned. In fact, owning a semaphore, 
as mentioned in the DosSemRequest description, does not apply to 
these function calls. 
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To allow a simple wait or post type of signalling between 
threads/processes, several function calls are provided: 



DosSemSet 



Set a semaphore. 



DosSemSetWalt Set a semaphore and wait for it to be cleared. 
DosSemWait Wait for a semaphore to be cleared. 
DosMuxSemWait Wait for any one of many semaphores to be 



System Semaphore Function Calls 

The function calls provided to support the allocation, access authori- 
zation, and deallocation of system semaphores are: 



Starting and Stopping a Thread's Execution 

For explicitly controlling when a thread can execute, the following 
function calls are provided: 

DosResumeThread Restart a thread's execution. 
DosSuspendThread Suspend a thread's execution. 



cleared. 



DosCloseSem 

DosCreateSem 

DosOpenSem 



Close a system semaphore. 

Create a system semaphore. 

Open an existing system semaphore. 
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IPC Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The Interprocess Communication function calls provided are summa- 
rized as follows: 

DosCloseQueue 
DosCloseSem 
DosCreateQueue 
DosCreateSem 
DosMakePIpe 
DosMuxSemWalt 

DosOpenQueue 
DosOpenSem 
DosPeekQueue 
DosPurgeQueue 
DosQueryQueue 
DosReadQueue 
DosResumeThread 
DosSemClear 
DosSemRequest 
DosSemSet 
DosSemSetWait 
DosSemWait 
DosSuspendThread 

Suspend a thread's execution. 
DosWrlteQueue Add an element to a Queue 



Close a Queue 
Close a system semaphore. 
Create a Queue 
Create a system semaphore. 
Create a Pipe 

Wait for any one of many semaphores to be 
cleared. 
Open a Queue 
Open a system semaphore. 
Get an element from Queue, but do not remove it 
Purge all entries from a Queue 
Find how many elements are in Queue 
Get an element from a Queue and remove it 
Restart a thread's execution. 
Clear a semaphore. 
Obtain a semaphore. 
Set a semaphore. 

Set a semaphore and wait for it to be cleared. 
Wait for a semaphore to be cleared. 
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Asynchronous Notification 



Signals allow a process to Intercept and deal with a variety of traps 
and external events. The signal facility allows a program to specify 
an on condition handler routine which is executed when the event 
occurs. 

Examples of events that can cause signal handlers to be executed 
are: 

• Control-Break (or Control-C) key pressed 

• Program terminated via DosKillProcess 

Each process can define a process-unique signal handler for any 
signal. 

Signals fall Into two categories, traps and external events. Trap 
events are synchronous in that they are a result of an instruction exe- 
cuted by one of the process's threads. Most program traps (such as 
divide by 0) are handled via the DosSetVec function call. All other 
signals are external events. 

An Incoming signal is handled in one of several ways: 

• The default action, typically IGNORE or TERMINATE PROCESS. 

• If the process has specified a signal handling address and the 
exception is a trap, the thread causing the trap will execute the 
signal handler routine. The thread executes that handler imme- 
diately. 

• If the process has specified a signal handling address and the 
exception is an external event, thread 1 (the original task thread) 
is diverted, in a forced far call analogous to a hardware interrupt, 
to the proper signal handler address. Because a signal repres- 
ents a time-critical event, if thread 1 is in the midst of a function 
call that does not complete quickly then the function call is 
aborted. The signal interrupt takes place immediately upon 
return from the OS/2 service call. Slow calls aborted In this 
manner are primarily device I/O calls. File function calls 

(disk open/close/read/write) are not normally aborted. 
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An application wliicli expects to make non-emergency use of 
signais should reserve thread 1, perhaps by having it bloclc upon 
an eternally reserved RAM semaphore, and use another thread 
for program execution. 



Asynchronous Notification Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The Asynchronous Notification function calls provided are summa- 
rized as follows: 

DosHoldSlgnal Disable/Enable signal processing 
DosFlagProcess Set process external event flag 
DosSendSignal Send CTL-C or CTL-Breal< signal 
DosSetSlgHandler Define a routine to handle a signal. 
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Program Execution Control 



Dynamic Linking 

Dynamic linking is tlie delayed binding of external references. There 
are two forms of dynamic linking: 

• Load time 

• Run time. 

Dynamic link routines, both load time and run time, are shared by 
invoking applications. Both the code and the data segments of a 
dynamic link routine are shared (unless the nonshared data option is 
selected during the module link process). It is a dynamic link rou- 
tine's responsibility to serialize access to its shared data segments. 

Note: A dynamic link routine can allocate nonshared memory. 

In load time dynamic linking, a program calls a dynamically linked 
routine just as it would any external routine. When the program is 
assembled or compiled, a standard external reference is generated. 
At link time, the programmer specifies one or more libraries con- 
taining routines to satisfy external references. External routines to 
be dynamically linked contain special definition records in the library. 
A definition record tells the linker that the routine in question is to be 
dynamically linked and provides the linker with a dynamic link 
module name and entry name. The module name is the name of a 
special executable file with the filename extension of .DLL which con- 
tains dynamic link entry points. The linker stores module name or 
entry name pairs describing the dynamic link routines in the .EXE file 
created for the program. When the calling program is run, OS/2 loads 
the dynamic link routines from the modules specified and links the 
calling program to the called routines. 

To invoke run time dynamic iinicing, the application uses the function 
calls described in this section. 

A dynamic link module can have an optional Initialization routine. 
This routine is invoked when the dynamiolink module is first loaded, 
before any dynamic link routine is actually called. The initialization 
routine is the entry point specified on an END statement in one of the 
Assembler source files of the dynamic link module. Only one source 



4-26 



file can have an END statement identifying an initialization routine. If 
no entry point is specified on any END statement, no initialization 
routine is called. Input to the initialization routine is as follows: 

AX = Module handle. 

SI = HEAPSIZE parameter from the .EXE file. 

Dl = Module handle for the dynamic link module. 

OS = The library's DQROUP data segment if one exists. Other- 
wise, DS = The application's OS. 

Initialization routines exit via far return. Contrary to the standard 
convention, initialization routines set AX not equal to zero to indicate 
success and AX equal to zero to indicate failure. 

Demand Load 

The OS/2 demand load function supports loading code segments on 
demand when called during the execution of a program, as opposed 
to preloading all code segments before program execution begins. 
Code segments are discarded as required to provide space for other 
uses. Code segments which are demand loaded, as opposed to pre- 
loaded, are identified in the .EXE file header for the program. 

Demand Load is enabled only when swapping is turned on. 

Demand load is supported for the code segments of any program, not 
just for dynamic link routines. 

I/O Privilege Model 

Although OS/2 applications do not have I/O privilege, subsystems can 
have routines which execute with I/O privilege. Code (and data seg- 
ments) requiring I/O privilege can be flagged when the subsystem is 
linked. Refer to "Dynamic Linking" on page 4-26. 

A routine requiring I/O privilege is allocated a 512-byte stack. Seg- 
ments executing with I/O privilege may not contain links to any other 
segments or modules. Such segments cannot issue OS/2 calls. 

Starting programs which require I/O privilege can be controlled by 
the CONFIG.SYS parameter lOPL. 
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EXE File Information 



The OS/2 .EXE file provides support for segmented programs and 
80286 protect mode programs. An OS/2 .EXE file represents either an 
application or a module containing dynamic link entry points. 

The following items are applicable to applications only: 

• Segment #:offset of entry point 

• Segment # passed in DS on program invocation 

• Segment #:offset of stack 

• Stack size 

The following items are kept on a per segment basis: 

• Code or data 

• If code segment, pre-load versus demand load 

• If data segment, whether segment is read only or read/write 

• Whether segment requires I/O privilege 

• Fix up records for external references including 

- References resolved within this .EXE file 

— References resolved via dynamic link. These include module 
name/entry point name pairs and/or module name/entry point 
ordinal pairs. Each pair identifies a dynamic link module 
(.DLL file) and a dynamic link routine within that module. 

• Fix up records to support 80287 emulation 

• Fix up records to support huge addressing 

• Debug Information. 

The following Items are kept per far call entry point: 

• Entry point name 

• Whether the entry point name is exported 

• Segment #:offset of entry point 

• The number of parameters which must be copied from the call- 
er's stack to the callee's stack when an entry point requiring I/O 
privilege is invoked. 
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Program Execution Control Function Call Summary 



For function call details, refer to Technical Reference, Vol. 2. 



The program execution control function calls provided are summa- 
rized as follows: 



DosFreeModule 

DosGetProcAddr 

DosGetModHandle 

DosGetModName 

DosLoadModule 



Free Dynamic Link Module 
Get Dynamic Link Procedure Address 
Get Dynamic Link Module Handle 
Get Dynamic Link Module Name 
Load Dynamic Link Module 



Errors and Exceptions 

Errors from Function Requests (Return Codes) 

All function calls return AX = 0 if the operation is successful. If an 
error condition is encountered, AX = an error code. 

For function call return codes and return code details, refer to Tech- 
nical Reference, Vol. 2. 

Hard Error Override 

Hard error processing occurs without direct application notification. 
In the event that an OS/2 application needs to process these events, a 
new function call (DosError) is provided. This allows the application 
program to notify OS/2 that all permanent errors associated with the 
process, or an open handle belonging to the process, are to be 
reflected as immediate failures. 



Handling Machine Exceptions 

An application can provide a routine to process machine exceptions 
occurring while it is executing. This allows language libraries to 
furnish 287 emulation or error recovery routines. 



4-29 



Errors and Exceptions Function Caii Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The errors and exceptions function calls provided are summarized as 
follows: 

DosError Allows a process to receive hard error notifica- 

tion without generating a hard error signal. 
DosSetVec Establish Handler for Exception Vector. 



OS/2 Message Functions (Message Retriever) 

The Message Retriever provides an application message functions to 
retrieve and insert variable message information, insert message 
text, and output messages. 

IViessage Functions Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The function calls provided are summarized as follows: 

DosGetlMessage Get a system message with variable text 
inserted. 

DosinsMessage Insert variable text string information into body of 
message. 

DosPutn/iessage Output a message to the supplied handle. 



Program Startup Conventions 

The rules on the content of various data areas and registers on 
program entry and termination are different for old programs than 
new programs. 

For old programs, the conventions of DOS 3.3 apply. 

For programs linked with OS/2, the new conventions are: 
• There is no Program Segment Prefix (PSP) 
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• The environment, program pointer, and arguments are passed in 
a segment (selector in AX) 

Wlien the Indicated program Is given control, it will receive a pointer 
to a copy of the environment followed by a copy of the PgmPointer 
string followed by two argument strings. The following sample shows 
how to start a typical OS/2 program. 



Environment: 



ASCIIZ string 1 
ASCIIZ string 2 



environment string 1 
environment string 2 



ASCIIZ string n 
Byte of 0 



environment string n 



Program Pointer: ASCIIZ 



; string of filename 
; of program to run. 



Arguments : 



ASCIIZ 
ASCIIZ 
Byte of 0 



; argument string 1 
; argument string 2 



Environment consists of a list of strings typically having the following 
form: 

parameter = value 



Program Pointer is an ASCIIZ string of the drive, directory path, and 
filename of the program being executed. 

Arguments consist of two strings representing command parameters 
for the program as opposed to the environment parameters. When a 
program is started from the command line, CMD.EXE will set argu- 
ment string 1 to the program name as it was entered on the command 
line. Argument string 2 will contain program parameters as entered 
on the command line. 



Shown below is a dump of a sample environment, program pointer, 
and argument area. The dump was obtained after entering the fol- 
lowing command: 

c:src\startup 1111 2222 3333 4444 5555 6666 7777 8888 
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Sample Dump 



AX=004F BX=G03F CX=00C3 DX=0000 

IP=0000 CS=001F DS=002F ES=0000 

GDTR=1172E0 3D07 IDTR=11B000 03FF 
001F:0000 CC INT 3 



SP=O200 BP=0000 SI=0000 DI=0088 
SS=003F NV UP EI PL NZ NA PO NC 
TR=0010 LDTR=0028 I0PL=2 MSW=PM EM IS 



004F:0000 33 58 42 4F 58 3D 43 4F-4D 4D 41 4E 44 2E 43 4F 3XBOX=C0MMAND.CO 

004F:0010 4D 00 50 41 54 48 3D 00-43 4F 4D 53 50 45 43 3D M. PATH=.COMSPEC= 

004F:0020 41 3A 5C 43 4D 44 2E 45-58 45 00 00 43 3A 5C 53 A:\CMD.EXE. .C:\S 

004F:0030 52 43 5C 53 54 41 52 54-55 50 2E 45 58 45 00 63 RC\STARTUP.EXE.c 

0O4F:0040 3A 73 72 63 5C 73 74 61-72 74 75 70 00 20 31 31 :src\startup. 11 

004F:0O50 31 31 20 32 32 32 32 20-33 33 33 33 20 34 34 34 11 2222 3333 444 

004F:0060 34 20 35 35 35 35 20 36-36 36 36 20 37 37 37 37 4 5555 6666 7777 

0O4F:007O 20 38 38 38 38 00 00 00-00 00 00 00 00 00 00 00 8888 



The following registers are set on program entry: 



CS:IP Points to the program initial entry point specified in the 
.EXE header. 

SS:SP Points to the stack specified in the .EXE header. 

DS Points to the data segment specified in the .EXE header. 

When the program does not contain an automatic data 
segment, DS will contain zero and the program must ini- 
tialize DS if necessary. 

ES 0 

AX Environment segment handle (selector). 

BX Offset in environment of command line start 

CX Length of data segment (0 = 65536) 

DX STACKSIZE parameter from the .EXE file. 

SI HEAPSIZE parameter from the .EXE file. 

Dl Module handle for the application executable. 

BP 0 



There are functions provided specifically for program startup. These 
functions allow an application to tailor its operation to specific ver- 
sions of DOS. The function calls are: 

DosGetEnv Get the Environment String. 

DosGetVersion Returns the DOS version number. 
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Chapter 5. Session Management 



The top layer of the session manager is caiied the sheii. The shell 
Interfaces with the application user. The OS/2 shell Is the Program 
Selector. The Program Selector allows the application user to start 
and switch among sessions. One DOS mode and multiple OS/2 mode 
sessions are supported. 

The shell uses lower level session manager functions to start and 
switch among applications. Each application runs in Its own session 
and has its own screen. One session is visible and is caiied the fore-^ 
ground session. The other sessions are called background sessions. 
Background OS/2 sessions continue to run until they issue some func- 
tion which causes them to wait, for example, request keyboard input. 
The DOS mode is frozen in the background. 

The video, keyboard, and mouse subsystems support the session 
manager. Screen, keyboard, and mouse I/O are routed on a per 
session basis. The session manager with the assistance of the video 
subsystem saves the contents of the screen over a screen switch. 
Application participation, reference "VIO Screen Save/Restore 
Operations" on page 6-20, is required to save the contents of the 
screen for graphics modes. 
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The following diagram shows the Program Selector and the 
display/keyboard/mouse routing features of the Session Manager. 



User Program Selector 
(and Session Switching) 
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Session Manager Application Support 



The following session manager functions are available to OS/2 mode 
application programs: 

1. Start a program in another session and include the started 
program in the switch list. The new session becomes a child 
session of the calling program's session. Child sessions may be 
manipulated by the parent session as follows: 

• Enable a parent session to switch one of its child sessions to 
the foreground. 

• Enable a parent session to set one of its child sessions 
selectable or non-selectable. 

This option affects selections made by the operator from the 
shell switch list. It does not affect selections made by the 
parent session. 

• Enable a parent session to bind one of its child sessions to 
itself so that, when the parent session is selected, the child 
session is brought to the foreground. 

This option affects selections made by the operator from the 
shell switch list. It does not affect selections made by the 
parent session. 

• Enable a parent session to terminate one or all of its child 

sessions. 

Note: Although a parent session/child session relationship 
exists, a parent process/child process relationship does not exist. 
Refer to the paragraph "Parent/Child Relationship:" in the 
Remarks section of DosStartSession in Technical Reference, Vol. 
2. 

2. Start a program in another session and include the started 
program in the switch list. No relationship is established 
between the new session and the calling program. 



5-3 



Restrictions 

The session mahager interfaces described in this section may not be 
issued under the following conditions: 

1. By a process started by RUN= in CONFIG.SYS. 

2. By a process started by the Detach command. 

3. During a VIO popup (by a process which has issued VioPopUp 
and not yet issued VioEhdPopUp). 

A total of 12 sessions may be started, whether by the operator 
through the shell menu or by an application through the API 
described in this section. 

Session manager API calls issued by background processes will be 
blocked during a hard error or VIO popup. 

Session Management API Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The session management API function calls are summarized as 
follows: 

DosSelectSessIon Select Session 
DosSetSession Set Session Status 
DosStartSesslon Start a Session 
DosStopSesslon Stop Session 
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Chapter 6. I/O Services 



OS/2 provides I/O access to the major character and block devices 
through function calls. Some devices are accessed through function 
calls specific to the device, such as the keyboard (KBD) and video I/O 
(VIO) calls. A device such as a disk is accessed using file system 
function calls. In addition, the file system API is used to access any 
named character device, such as LPT1 or C0M1, 

Many I/O function calls use a parameter called a handle. A handle is 
a 16-bit value that refers to a particular device or file. 

ASCIIZ Strings 

Several I/O function calls accept an ASCIIZ string (an ASCII string ter- 
minated by a byte of binary zeros) as input. 

Country Considerations: ASCIIZ strings can be composed of mixed 
single- and double-byte characters, and can be used in the following 
cases: 

• Filename and filename extension 

• Path name 

• Directory name 

Filename Specification 

The OS/2 standard filename consists of 1 to 8 bytes (characters), 
optionally followed by a dot and extension. The standard filename 
extension consists of 1 to 3 bytes (characters). This 8.3 limit on the 
format may be expanded in the future; programs should not parse 
filename strings. 

Leading blanks are not allowed In the filename specification. ASCII 
characters less than 20H are illegal as well as the following 
characters: 

<> + =;.."/ \ [ ] 

A period (.) or dot is the delimiter between filename and extension. 
The standard filename definition of 8.3 bytes means that name 
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formats longer than 8.3 received from OS/2 mode applications are not 
truncated to the 8.3 format and considered acceptable. Instead, they 
are classified as erroneous names. 

Name formats received from DOS 3.3 applications running in the DOS 
mode will be truncated to the 8.3 format. The resulting name is con- 
sidered acceptable. 

Name formats received from new applications written to the Family 
API and running under the DOS mode are not truncated to the 8.3 
format. Instead, they are classified as erroneous names. This 
insures that the Family API behaves the same whether running in the 
DOS mode or the OS/2 mode. 

Verification of valid filename characters uses the Country Support 
CDIDS (Country Dependent Information Data Structures) for Double 
Byte Character Set (DBCS) environmental vector and for file system 
character names. Refer to Chapter 11, "Country Support 
Considerations" on page 11-1 for more information. 

Country Considerations: If the 8th byte of a filename or 3rd byte of the 
extension is the first byte of a double-byte character, then the name 
or extension is not truncated to 7 bytes or 2 bytes respectively, but 
instead is reported as an error. 

Filenames can be entirely single-byte, mixed single- and double-byte 
or entirely double-byte characters. The use of a double-byte char- 
acter counts as two bytes. All double-byte characters can be used, 
with the exception of double-byte space. 
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Device Names 

The operating system has reserved certain names for devices sup- 
ported by the base device drivers. These device names are listed as 



follows: 




COMi-COMS 


First through third serial ports 


CLOCK$ 


Clock. 


CON 


Console keyboard and screen 


SCREENS 


Screen. 


KBD$ 


Keyboard 


LPT1 or PRN 


First parallel printer 


LPT2 


Second parallel printer 


LPT3 


Third parallel printer 


NUL 


Nonexistent (dummy) device 


POINTERS 


Pointer draw device (Mouse screen support) 


MOUSES 


Mouse 



These names can be used in the DosOpen function call to OPEN the 
corresponding devices. Note that these reserved device names take 
precedence over filenames; the OPEN always checks for a device 
name before checking for a filename. The only exception is that 
C0M1-C0M3 are only reserved device names when the ASYNC 
(RS232-C) Device Driver is loaded. This means that a filename which 
matches a reserved device name can never be OPENed, because the 
device will be OPENed instead. 

Code Page Support 

OS/2 code page management reads keyboard input and writes 
display and printer output for concurrent multiple processes that 
input and output ASCII based character data encoded in different 
code pages. 

A code page defines a character set by assigning each character to a 
location in a code page table. A character set is implemented by 
using a "character shape" table from which a character is selected 
for output by Its associated display or printer. A character set is 
either downloaded to a device or ROM resident at the device. 

The system accomplishes this by switching the required code page 
for a code page supported device prior to input or output. 
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The required code page is the current code page of the process at the 
time it opens a device or a specific code page selected by the 
process with a set code page API function. A character set can also 
be plugged In the device, such as the Quietwrlter® IIP printer. 

In addition, the country APIs retrieve country and language 
dependent information in the current code page of the calling process 
or In a code page selected by the process. 

Code Page Management 

Code Page Management allows a user to select a code page for key- 
board input and screen and printer output before running an applica- 
tion, a system command or utility in the OS/2 multitasking 
environment. This allows the user in a particular country such as 
England (code page 437) or Norway (code page 865) or language 
region such as Canadian-French (code page 863) to run with a code 
page that defines an ASCII-based character set containing characters 
used by that particular country or language. 

OS/2 supports the following code pages: 

437 U.S. IBM PC code page 

850 Multilingual code page 

860 Portuguese code page 

863 Canadian-French code page 

865 Nordic code page 

OS/2 allows the user to prepare one code page or a combination of 
two code pages from the above list. Installable code page files 
include keyboard translate tables, display character sets, printer 
character sets, and country/language information for each code page 
supported. 

The primary features of Code Page Management are: 

• User commands (CODEPAGE and DEVINFO) in CONFIG.SYS for 
commanding system initialization to prepare selected code pages 



*> Quietwrlter Is a registered trademark of 
International Business Machines Corporation 
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and devices for code page switching at run time wlien in char- 
acter text modes. 

• An OS/2 user command (CHOP) to change the code page of Its 
session (command process that executes CHOP) and any applica- 
tion that runs in that seission. CHOP affects printer code pages 
only on print jobs that are opened subsequent to the command. 

• API functions for an application to set and query code page for a 
process, keyboard input, video output, and spooled printer output. 

• System code page switching of keyboard, display, 
printer/spooler, and country information for concurrent processes 
in different code pages. 

One system country code, one system keyboard layout, and up to two 
system code pages can be configured for system use at run time. 

Code Page Dependent Information 

System information dependent on the code page includes: 

• Video character set for display 

• Keyboard translate table for scan code to character conversion 

• Printer translate table and ROM code pages for printer 

• Country format information for time, date, and other formats 

• Language collate sequence table for character string sorting 

• Language case map table from lower to upper case 

• Language DBOS environment vector of lead bytes 

This information is created at system initialization and maintained in 
system storage by OS/2 for each system code page that is prepared 
and is retrieved as needed according to code page. 

Code Page Switching Examples 

Some examples of code page switching that can occur are: 

• The printer character set is switched by the Print Spooler to the 
process code page (that opens the printer) before it outputs the 
process write data stream to the printer. 

• A process requests DosGetCtrylnfo for the country information of 
the system country code or another selected country code and 
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the information is provided encoded in ttie code page of the 
process. 

Switching the display to the code page that a system ASCII message 
is encoded in prior to output is not provided. 

Data file code page tagging and code page switching based on the 
file code page tag Is not provided. Also, filenames created under one 
code page may not be accessible by that name under another code 
page because the name characters may case map differently. This 
can be avoided by using only the first 128 characters of a code page 
for filenames or only unaccented characters (a-z, A-Z, and 0-9). 

Code Page Preparation 

During system initialization the selected code pages specified in the 
CODEPAGE command are prepared to allow run time code page 
switching of the display, the keyboard, the printer(s), and the country 
Information. The display, keyboard, and printer(s) to be prepared 
must be defined in a DEVINFO command. Country information is pre- 
pared for the system country code specified in the COUNTRY 
command. If a resource cannot be prepared for the selected code 
page(s), then it is prepared for a default code page. 

System resources default in the following ways at system initializa- 
tion for code page preparation when the code page cannot be found 
for the resource. 

• A keyboard layout defaults to the code page of the translate table 
designated as the default layout in the KEYBOARD. DCP file. The 
default layout is based on the national code page of its associ- 
ated country. KEYBOARD.DCP must be explicitly specified in the 
DEVINFO statement for the keyboard in CONFIG.SYS. 

• The display defaults to the code page of ROM_0 for the device. 

• The printer defaults to the code page of ROM_0 for the device. 

• The country information defaults to the code page of the first 
entry found in the COUNTRY.SYS file for the country code. Each 
entry is the same information for a given country code but 
encoded in a different code page. The first entry is based on the 
preferred country code page. 

Note: ROM_0 means a device default code page which is the device 
native code page or the lowest addressed ROM code page. 
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In the following table, countries are shown on the left, country codes 
are shown next, their default code page assignment is listed in the 
third column, and country keyboard layouts are shown on the right. If 
country information cannot be prepared at system Initialization 
because it is not found in the COUNTRY.SYS file for a code page 
selected with the CODEPAQE command, then it is prepared (main- 
tained for run time code page switching in memory) in the default 
code page. Similarly, a keyboard layout is prepared in its default 
code page if it cannot be prepared in the selected code page because 
It Is not found in the KEYBOARD.DCP file. COUNTRY.SYS contains 
one default entry per country code and KEYBOARD.DCP contains one 
default entry per keyboard layout based on these assignments: 



Country 


Ctry 
Code 


Code 
Page 


Kbd 


Asia 


099 


437 


- 


Australia 


061 


437 


- 


Belgium 


032 


437 


BE 


Canada 


002 


863 


CF 


Denmark 


045 


865 


DK 


Finland 


358 


437 


SU 


France 


033 


437 


FR 


Germany 


049 


437 


GR 


Italy 


039 


437 


IT 


Latin America 


003 


437 


LA 


Netherlands 


031 


437 


NL 


Norway 


047 


865 


NO 


Portugal 


351 


860 


PC 


Spain 


034 


437 


SP 


Sweden 


046 


437 


sv 
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Country 


Ctry 
Code 


Code 
Page 


Kbd 


owiTzenanu 






or, ova 


United Kingdom 


044 


437 


UK 


United States 


001 


437 


US 



Altliough only up to two code pages can be selected with the 
CODEPAGE command, the system may actually have prepared three 
or more code pages at system Initialization in case a system 
resource defaults on code page preparation. For example, the key- 
board may be prepared for a default code page that Is different than 
the two selected code pages for which the display is successfully pre- 
pared. 

Code Page Operation 

Each process has a code page tag maintained by the OS/2 kernel. A 
code page is a table that defines how characters are encoded. A 
code page tag Is the identifier of the current code page for the 
process. See the IBM Operating System/2™ Programmer's Guide for 
a description of code pages and the /6M Operating System/2'^ 
User's Reference for information on configuring code pages for the 
system. 

A child process inherits the code page tag value of its parent. The 
default code page for the first process of a program started in a 
session is the same as the session code page. The default code page 
for a new session is the primary code page specified in the 
CODEPAGE configuration command. A process code page tag may 
be changed with the function call DosSetCp or DosSetProcCp and 
queried by DosGetCp. However, DosSetCp or DosSetProcCp does 
not change its parent or any child process code page tags. See TecAi- 
nical Reference. Vol. 2 for details about these function calls. 
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The following explains what code page is used when performing 
process input and output: 

• Spooled printer output by a process is printed by the spooler in 
the code page of the process. The code page that the spooler 
uses to print is established through the system spooler and file 
system at the time the process makes an open printer request. 

• Video output by a process is shown by the Video Subsystem in 
the current code page of the implied video handle being used for 
output by the process. The default display code page for a new 
session is the primary code page specified in the CODEPAGE 
configuration command or defaults to the display ROM code 
page. The display code page can be changed by a process with 
VioSetCp or DosSetCp for the logical display of the session to 
which the calling process belongs. 

• Keyboard scan code input is converted into ASCII characters by 
the keyboard device driver in the current code page of the key- 
board handle being used for input by a process. The default key- 
board handle code page for a session is the primary code page 
specified in the CODEPAGE configuration command or defaults to 
US437. The keyboard code page can be changed by a process 
with KbdSetCp or DosSetCp for the logical keyboard of the 
session to which the calling process belongs. 

• Utility and command output is shown in the current code page of 
the command process which executes the function. 

An invocation of a CMD.EXE process in OS/2 or a C0MMAND.COM 
process in the DOS mode is a session. Therefore, the code page of 
the command process is the session code page. The user command 
CHOP is provided to change the code page of a session. CHOP per- 
forms the following functions: 

• Sets the session's command process code page 

• Sets the session's logical display code page 

• Sets the session's logical keyboard code page. 

The printer code page is based on the process code page at the time 
the process makes an open printer request. No special command is 
needed for the printer. 
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Code Page Supported Devices 

Device code page support is provided for the keyboard and certain 
printer and display devices with code page download and switch 
capability. 

The devices supported by OS/2 code page switching include: 

• IBM Personal System/2™ Display Adapter 

• IBM Proprinter™2 

• Quietwriter® ll|3 

• Enhanced Graphics Adapter (EGA) 

• Video Graphics Array (VGA) 

Special Considerations and Limitations 

Code Page Management has these special considerations and 

limitations: 

• One system country code is prepared at system initialization and 
cannot be changed at run time; however, information for other 
country codes can be retrieved through the Country API for 

country information. 

• One or two system code pages may be prepared at system initial- 
ization. The user can switch (CHOP) between them and so can a 
program through the API described in the following section. The 
system code pages are prepared based on CONFIG.SYS com- 
mands and system initialization and cannot be changed at run 
time. 

• One system keyboard layout is prepared at system initialization 
and can be changed at run time using the KEYB utility. The new 
selected keyboard layout replaces the current keyboard translate 
tables for the system code pages defined by the CODEPAGE 
command in CONFiG.SYS, if the selected layout is available in 
those code pages. 



2 Proprlnter is a trademark of 
International Business Machines Corporation 

3 Quietwrlter is a registered trademark of 
International Business Machines Corporation 
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The CODEPAGE command allows preparation for up to two 
selected code pages. However the system may actually have 
more than two different code pages active In the system in these 
cases: 

— System Initialization defaults to a code page different than the 
selected code pages for a printer character set, display char- 
acter set, keyboard layout or the country Information when 
the selected code page Is not available. 

— KEYB defaults to a different code page for the l<eyboard 
layout If It is not available in a selected code page. 

— An application uses printer lOCtI to activate additional printer 
code pages. 

The CHCP command only changes the code page of the 
command process to which it belongs and does not affect the 
code page of any other existing command process, other process 
or other subsystem handle. Its purpose Is to allow the user to 
change the code page of the session. 

The user can switch between two prepared code pages with the 
CHCP command and the application can switch between code 
pages with the appropriate APIs. The primary (default) system 
code page is used throughout the system and by all applications 
If a switch never occurs following system initialization. If no 
system code pages have been prepared, then the system runs 
with the default code page available per device, country informa- 
tion, and keyboard layout. 

An application controls the appearance of its screen display char- 
acteristics when using OS/2 APIs to switch code pages. Charac- 
ters may not appear the same for different code pages. The 
application can offer code page selection to the user, if required, 
through its own application user interface. 

The OS/2 system spooler must be installed for printer code page 
switching or be replaced by another printer monitor that receives 
code page commands from the printer device driver and provides 
the code page function support. 

It Is possible for an application to Issue printer lOCtI commands 
to activate different code pages throughout its printed data 
stream. However, no data stream format is defined by OS/2. 
Imbedded escape sequences and printer control codes are 
allowed and not monitored by OS/2. 
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• OS/2 does not automatically switch to the code page of a 
filename and does not keep track of the code page of a filename. 
This allows the following possible situations to occur: 

— The file is not accessible under a different code page 
because the filename is not recognized in that code page 
although valid in the original code page in which it was 
created. 

- The wrong file becomes accessible under a different code 
page because the keyboard entered filename maps to a dif- 
ferent but valid filename in that code page. 

• The system does not automatically switch to the code page of a 
message prior to output. Therefore, messages encoded in a par- 
ticular code page may not be fully readable in another code page. 

Code Page API Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The code page function calls are summarized as follows: 
DosSetCp Set the code page of the calling process and the 



VIoSetCp 
VIoGetCp 
KbdSetCp 
KbdGetCp 



Printer lOCtI 



DosSetProcCp 
OosGetCp 



session's display and keyboard code page 

Set the code page of the calling process 

Get the code page of the calling process and the 

system code page(s) 

Set a video subsystem code page 

Get a video subsystem code page 

Set a keyboard subsystem code page 

Get a keyboard subsystem code page 

Requires Print Spooler to be installed 

• Activate a printer code page 

• Get the active printer code page 

• Validate a printer code page 
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System Initialization 



OS/2 runs on the Personal Computer AT® model group, Personal 
Computer XT™ Model 286 model group, and the PS/2 model group. 
This is supported by loading the correct set of device drivers by 
model group. A different set of reserved filenames will contain the 
base device drivers for each supported model group that are not 
loaded by CONFIG.SYS processing. The kernel adapts itself to the 
correct model in the hardware-dependent areas that are not device 
driver related. 

Hardware Characteristics 

OS/2 assumes that the following characteristics of PS/2 devices are 
statically assigned before OS/2 initialization: 

• "Sleep" or "wake" status 

• Interrupt level 

• I/O port(s) 

These device characteristics may not change after OS/2 initialization 
has begun. 

Device Driver Instaliation 

OS/2 automatically loads all base device drivers, which are model 
group dependent. OS/2 and the system installation procedure are not 
dependent on the specification of any device drivers in the 
CONFIG.SYS file for normal system operation. 

The system install process inserts the appropriate DEVICE = state- 
ments for all user specified device drivers into the CONFIG.SYS file. 
The names of these device drivers are based on the type of device 
driver the user has specified and the model group on which the 
system install process is running. The system install process also 
copies the correct device driver file to the IPL volume. 

If the user wants to manually insert DEVICE = statements Into the 
CONFIG.SYS file, the user needs to ensure that the device dhver 
being installed is correct for the model group the system is started 
on. 
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CONFIG.SYS 



The CONFIG.SYS file must not contain DEVICE = statements for the 
base device drivers required for basic OS/2 operation. 

Device I/O Function Cali Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The device I/O function calls are summarized as follows: 

DosBeep Generate sound from spealter 

DosDevConfIg Get device configuration 

DosDevlOCtI I/O control for devices 

DosPortAccess Request I/O access to devices 

DosPliyslcalDlsk Partitionable Disk support 

DosCLI Access Request CLI/STI Access 



File I/O Services 

File handle values of FFFFH do not represent actual file handles but 
are used throughout the file system interface to indicate specific 
actions to be talcen by the file system. Usage of this special file 
handle where it is not expected by the file system results in an error. 

Note: Null pointers are defined to be OOOOOOOOH throughout this bool(. 

Existing file systems that conform to the Standard Application 
Program Interface (Standard API) described in this section, do not 
necessarily support all the described information kept on a file basis. 
When such is the case, file system drivers return to the application a 
null (zero) value for the unsupported parameter. 

Note: The order of processing of multiple outstanding requests 
issued by multiple threads is not guaranteed. See "Request Packets" 
on page 7-37 for a discussion of the order in which requests are 
issued to the API by multiple threads and the order in which the 
requests arrive at a device driver. 
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File I/O Function Cali Summary 



For function cali details, refer to Technical Reference, Vol. 2. 



The file I/O function calls are sumnriarized as follows: 



DosBufReset 

DosChDir 

DosCligFilePtr 

DosCiose 

DosDeiete 

DosDupHandie 

DosFiieLoclcs 

DosFindClose 

DosFindFlrst 

DosFlndNext 

DosMicDir 

DosMove 

DosNewSlze 

DosOpen 

DosQCurDIr 

DosOCurDisIc 

DosOFHandState 

DosQFilelnfo 

DosQFileMode 

DosQFsinfo 

DosQhIandType 

DosQVerHy 

DosRead 

DosReadAsync 

DosRmDir 

DosScanEnv 

DosSearcliPath 

DosSeiectDisIc 

DosSetFiieinfo 

DosSetFiieMode 

DosSetFHandState 

DosSetFslnfo 

DosSetlMaxFH 

DosSetVerIfy 

DosWrite 

DosWriteAsync 



Flush file buffers 

Change current directory 

Change (Move) the file read or write pointer 

Close file handle 

Delete file 

Duplicate file handle 

Lock or unlock multiple ranges of bytes in an 
opened file 

Terminate usage of a directory search handle 

Find first matching file 

Find next matching file 

Make subdirectory 

Move a file 

Change size of a file 

Open or create a file 

Query current directory 

Query current default drive 

Query file handle state 

Query file information 

Query file mode 

Query file system information 

Query handle type 

Query the verify setting 

Read from a file 

Asynchronous Read from a file 

Remove subdirectory 

Scan environment segment 

Search a path for a filename 

Select disk 

Set file information 

Set file mode 

Set file state 

Set file system information 
Define new maximum file handle 
Set verify setting 
Write to a file or device 
Asynchronous write to a file or device 
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Video I/O Services 



Display Adapters Supported 

OS/2 supports the following adapters: 

• Color Graphics Adapter (CGA) - Personal Computer AT® or Per- 
sonal Computer XT™ Model 286 

• Enhanced Graphics Adapter (EGA) - Personal Computer AT or 
Personal Computer XT Model 286 

• Video Graphics Array (VGA) - PS/2 only 

• IBM Personal System/2™ Display Adapter - Personal Computer 
AT or Personal Computer XT Model 286 

• IBM Personal System/2™ Display Adapter 851 4/A - PS/2 only 

Video I/O (VIO) services are provided for any one of these adapters. 
Configurations including multiple displays are not supported. 

Video Graphics Array (VGA) 

The VGA is EGA compatible with the exception that it has additional 
video modes. 

Differences between VGA and EGA include: 

• EGA does not run on the PS/2. 

• VGA runs ONLY on the PS/2. 

• VGA supports additional text and graphics modes 

• VGA starts in a different rriode than the EGA display. When a 
PS/2 monochrome display is present, the VGA starts in high 
resolution monochrome text mode (mode 7 + , 80x25 alphanu- 
meric text support with a 9x16 character cell and a 720x400 pixel 
resolution). When a PS/2 color display is present, the VGA starts 
in high resolution color text mode (mode 3+ , 80x25 alphanumeric 
text support with a 9x16 character cell and a 720x400 pixel resol- 
ution). The OS/2 software starts with this display set to normal 
video mode (white letters on a black background). 
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IBM Personal System/2''^ Display Adapter 

OS/2 supports the IBM Personal System/2™ Display Adapter and 
the IBM Personal System/2™ Display Adapter 8514/A. The IBM Per- 
sonal System/2™ Display Adapter is VGA-compatible and works on 
the Personal Computer AT and on the Personal Computer XT Model 
286. VGA-compatible modes are supported on the IBM Personal 
System/2™ Display Adapter. 

The IBM Personal System/2™ Display Adapter 8514/A is supported 
on the PS/2. VGA-compatible modes are supported on this adapter. 

VIO Support by Mode 

The following modes are supported by VIO: 

Text - Modes 0, 1, 2, 3 and their + and * variations, mode 7 and 
the + variation. 

Graphics - All Points Addressable (APA) modes 4, 5, 6, D. E, F, 10, 
11, 12, and 13. 

Note: Only a subset of VIO calls are supported in graphics modes. 
See "VIO Calls Supported in Graphics Modes" on page 6-19 for 
details. 

Not all modes are supported on all adapters. 
Text Modes Supported (Mono-Compatible) 

A/N represents Alpha/Numeric In the following charts. 

The following Text modes are supported by the EGA, VGA, and IBM 
Personal System/2™ Display Adapter: 



Mode 


Type 


Text 


Colors 


Cell 


Resolution 


7 


A/N 


80x25 




9x14 


720 X 350 


7 + 


A/N 


80x25 




9x16 


720 X 400 



Note: The ' + ' mode variation Is only supported by the VGA and IBM 
Personal System/2™ Display Adapter. 
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The following Text modes are supported by the CGA, EGA, VGA, and 
IBM Personal System/2™ Display Adapter: 



Mode 


Type 


Text 


Colors 


Cell 


Resolution 


0, 1 


A/N 


40x25 


16 


8x8 


320 X 200 


0*. 1* 


A/N 


40x25 


16 


8x14 


320 X 350 


0 + , 1 + 


A/N 


40x25 


16 


9x16 


360 X 400 


2, 3 


A/N 


80x25 


16 


8x8 


640 X 200 


2*, 3* 


A/N 


80x25 


16 


8x14 


640 X 350 


2 + ,3 + 


A/N 


80x25 


16 


9x16 


720 X 400 



Note: The variations on the above modes are only supported by 
the EGA, VGA, and IBM Personal System/2™ Display Adapter. The 
' + ' variations on the above modes are only supported by the VGA 
and IBM Personal System/2™ Display Adapter. For modes 0 and 2, 
the color burst is turned off on the CGA. 

VIO Calls Supported In Text Modes: 

All VIO calls are supported in text modes. 
Graphics Modes Supported 

The following graphics All Points Addressable (APA) modes are sup- 
ported by the CGA, EGA, VGA, and IBM Personal System/2™ Display 
Adapter: 



Mode 


Type 


Text 


Colors 


Cell 


Resolution 


4,5 


APA 


40x25 


4 


8x8 


320 X 200 


6 


APA 


80x25 


2 


8x8 


640 X 200 



Note: For modes 5 and 6, the color burst is turned off on the CGA. 
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The following additional APA modes are supported by the EGA, 
VGA, and IBM Personal System/a"™ Display Adapter: 



Mode 


Type 


Text 


Colors 


Cell 


Resolution 


D 


APA 


40x25 


16 


8x8 


320 X 200 


E 


APA 


80x25 


16 


8x8 


640 X 200 


F 


APA 


80x25 




8x14 


640 X 350 


10 


APA 


80x25 


16* 


8x14 


640 X 350 



* Only 4 colors are available on an EGA configuration with less than 
128Kb of video memory. 

The following additional APA modes are supported by the VGA and 
IBM Personal System/2™ Display Adapter: 



Mode 


Type 


Text 


Colors 


Cell 


Resolution 


11 


APA 


80x30 


2 


8x16 


640 X 480 


12 


APA 


80x30 


16 


8x16 


640 X 480 


13 


APA 


40x25 


256 


8x8 


320 X 200 



ViO Calls Supported In Graphics Modes 



The VIO calls supported in graphics modes are a subset of those 
VIO calls supported for text modes. The following calls are 
supported: 



VIoDeReglster 

VIoEndPopUp 

VIoGetConfIg 

VIoGetFont 

VioGetMode 

VIoGetPhysBuf 

VIoGetState 

VIoModeUndo 

VIoModeWalt 

VioPopUp 

VIoReglster 

VIoSavRedrawWalt 



Deregister a video subsystem 

Deallocate a popup display screen 

Get Video Configuration 

Get Font (request type 1 only) 

Get display mode 

Get physical display buffer 

Get Video State (request types 0 and 1 only) 

Undo previous restore mode registration 

Wait for restore mode notification 

Allocate a popup display screen 

Register a video subsystem 

Wait for screen save/redraw notification 
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VioSavRedrawUndo 

VioScrLock 

VioScrUnLock 

VioSetMode 

VioSetState 



Undo previous save/redraw registration 
Lock screen for I/O 
Unlock screen for I/O 
Set display mode 

Set Video State (request types 0 and 1 only) 



The other VIO calls, Print Screen, and Control Print Screen are not 
supported in graphics modes. 



VIO Screen Save/Restore Operations 

Screen save/restore operations are triggered in OS/2 by any of the 
following events: 

1. When the operator uses the hotkey to switch to another applica- 
tion, 

2. When an application issues DosStartSession (specifying fore- 
ground), 

3. When an application issues DosSelectSession, 

4. When an application issues VioPopUp (or a hard error popup is 
displayed), and 

5. When an application issues VioEndPopUp (or a hard error popup 
ends). 

For graphics modes, OS/2 notifies the application to perform the 
required save/restore operation. To be notified for events 1 through 3 
above, a graphics mode application issues VioSavRedrawWait. The 
return from the VioSavRedrawWait call provides the notification. A 
parameter returned on the call tells the application whether to 
perform a save or restore. To be notified for event 5, the application 
issues VioModeWait, and the return from VioModeWait is the notifica- 
tion. There is no notification for event 4. 



When an application's VioSavRedrawWait thread is notified to 
perform a save, the application must save the physical display buffer, 
video mode, state, and any other display adapter registers the appli- 
cation may have modified. 

When an application's VioSavRedrawWait thread is notified to 
perform a restore, it must restore the physical display buffer, video 
mode, state, and modified display adapter registers. When an appli- 
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cation's VioModeWait thread is notified to perform a restore, tlie 
application must restore the video mode, state, and modified display 
adapter registers. An application's VioModeWait thread does not 
restore the physical display buffer. OS/2 saves/restores the physical 
display buffer over a popup. 

Note that a screen switch may occur while the foreground application 
is currently accessing (under the protection of VIoScrLock) the phys- 
ical display buffer. In this case, the screen switch remains pending 
until either the application issues VIoScrUnLock or the screen lock 
times out. 

A graphics mode application must issue VioSavRedrawWait. A 
graphics mode application must issue VioModeWait only if it writes 
directly to the registers on the display adapter. If VioModeWait is not 
issued, OS/2 will restore the physical display buffer, mode, and state 
at the completion of a popup. 

Screen save and restore operations for text modes are performed 
automatically by OS/2. A text mode application must issue 
VioSavRedrawWait and VioModeWait only if it writes directly to the 
registers on the display adapter. 

An application's VioSavRedrawWait thread may be notified to 
perform a restore before it is notified to perform a save. This would 
happen if the application was running in the background when jt first 
issued VioSavRedrawWait. 

Note: The OS/2 Start command starts an application in the back- 
ground. 

VIO Code Page Support 

VIO code page support is provided for a subset of the display 
adapters supported in OS/2. VIO code page support is provided only 
for those adapters whose hardware supports down loadable fonts. 
The selection is limited to the following adapters: 

• EGA (Enhanced Graphics Adapter) - Personal Computer AT and 
Personal Computer XT Model 286 

• VGA (Video Graphics Array) - IBM Personal System/2™ only 

• IBM Personal System/2™ Display Adapter - Personal Computer 
AT® and Personal Computer XT™ Model 286 
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• IBM Personal System/2™ Display Adapter 8514/A - IBM Personal 
System/2™ only 

VIO allows an application to select one of two user-specified code 
pages as the current video code page. Alternately, the application 
may specify code page 0000 which corresponds to the ROM-resident 
code page. The following two VIO calls support code pages: 

• VioSetCp - sets the current video code page 

• VioGetCp - returns the current video code page 

VioSetCp can be used to specify one of the two code pages defined 
on the CODEPAGE statement in CONFIG.SYS. 

Code page 0000, the ROM-resident code page, may also be specified 
on VioSetCp. Code page 0000 is also used as the current video code 
page in the following cases: 

• No primary code page is Identified during system initialization. 

• A primary code page is identified, but the corresponding video 
code page file is not found. This case will occur if there is no 
DEVINFO statement identifying a video code page file in 
CONFIG.SYS, or if the video code page file identified is not found. 

Code page 0000 may not be specified on the CODEPAGE = statement 
in CONFIG.SYS. 

VioSetCp associates the code page specified on the call with the VIO 
handle also specified. Because handle zero is the only VIO handle 
supported, all threads and processes within a session share the same 
handle and current video code page. 

Applications may not manipulate the Character Map Select Register. 
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Video Font File Organization 



There is one video font file wliich contains all the fonts for all the 
code pages supported. Fonts are extracted from the video font file by 
the video subsystem. 

The video font file contains a file header and multiple font tables. 
Video Font File Header: The font file header is shown below: 



Font File Header Length 



Flags (Reserved = 0) 



Offset to Font Pointers 



# of Fonts in File 



Font #1 Offset 



Font #2 Offset 



Font #n Offset 



WORD 
WORD 
WORD 
WORD 



DWORD 
DWORD 



DWORD 
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Video Font Table Format: Each font table has the following format: 



Font Length (header + table) 



Font Header Length 



CodePage Id 



Font Type (Reserved = 0) 



Font Flags 



# of Pixel Columns in Cell, this Font 



# of Pixel Rows In cell, this Font 



# of Pixel Columns in Cell, Base Font 



# of Pixel Rows in Cell, Base Font 



Offset to Font Table 



Font Table Length in Bytes 



# of Code Points 



Lowest Code Point 



Highest Code Point 



Font for Lowest Code Point 



Font for Highest Code Point 



WORD 

WORD 

WORD 

WORD 

WORD 

BYTE 

BYTE 

BYTE 

BYTE 

WORD 

WORD 

WORD 

WORD 

WORD 



Font Specific 



Font Specific 



The Font Flags field has the following values: 
Bit 0 = 1 Partial font. 

Bit 1 = 1 Code points are included with each font. 
Bit 2-15 Reserved =0 
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Additional VIO Considerations 



• The default mode used in the OS/2 mode is the highest resolution 
supported by the primary display. Any conflicting switch settings 
on the adapter are ignored. 

• VIO calls issued by multiple threads and processes within a 
session are serialized via a semaphore. Applications with mul- 
tiple threads and processes issuing VIO calls within a session 
should be aware of the following potential lockout situations: 

— Issuing a VIO call within a critical section. This action will fail 
if the thread entering the critical section gains control at a 
time when another thread in the same process is in the 
middle of a VIO call. Reference DosEnterCritSec and 
DosExitCritSec in Technical Reference, Vol. 2 for more infor- 
mation. 

— Allowing a popup process to request a semaphore (or 
resource) owned by another process within the same 
session. This action will fail if the process owning the 
resource gets blocked on a VIO call. 



VIO Function Call Summary 



For function call details, refer to Technical Reference, Vol. 2. 



The VIO function calls are summarized as follows: 



VIoDeRegister 

VioEndPopUp 

VioGetAnsi 

VioGetBuf 

VioGetConfIg 

VioGetCp 

VioGetCurPos 

VioGetCurType 

VioGetFont 

VioGetMode 

VioGetPhysBuf 

VIoGetState 

VioModeUndo 

VioModeWait 

VioPopUp 

VioPrtSc 



Deregister video subsystem 

Deallocate a popup display screen 

Get ANSI status 

Get logical video buffer 

Get video configuration 

Get code page 

Get cursor position 

Get cursor type 

Get font 

Get display mode 

Get physical display buffer 

Get video state 

Undo previous restore mode registration 
Wait for restore mode notification 
Allocate a popup display screen 
Print screen 
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VioPrtScToggle 
VioReadCellStr 
VioRegister 



Ctrl-PrtSc notification 

Read character attribute string 

Register video subsystem 



VioReadCharStr Read cliaracter string 
VioSavRedrawWait Wait for screen save/redraw notification 
VioSavRedrawUndo Undo previous save/redraw registration 



DOS Mode EGA Considerations 

For some DOS mode EGA applications, OS/2 will not be able to 
switch from DOS mode to OS/2 mode and then back again. Upon 
return to the DOS mode application, the screen will be incorrect. The 
DOS mode EGA applications that do not run successfully are: 

• Applications that download fonts into a character generator block 
other than block 0; Character generator block 0 is supported. 
(See EGA ROM BIOS function call INT 10H, AH = 11H.) 

• Graphics mode applications that use more than one display page. 

• Advanced graphics mode applications that write directly to the 
registers on the EGA adapter. 



VioScrLock 

VioScrUnLock 

VIoScrollDn 

VioScroiiLf 

VioScrolIRt 

VioScrollUp 

VioSetAnsi 

VioSetCp 

VioSetCurPos 

VioSetCurType 

VioSetFont 

VioSetMode 

VIoSetState 

VioShowBuf 

VioWrtCellStr 

VioWrtCharStr 

VIoWrtCharStrAtt 

VioWiiNAttr 

VIoWrtNCell 

VIoWrtNChar 

VIoWrtTTY 



Lock screen for I/O 
Unlock screen for I/O 
Scroll screen down 
Scroll screen left 
Scroll screen right 
Scroll screen up 
Turn ANSI on or off 
Set code page 
Set cursor position 
Set cursor type 
Set font 

Set display mode 
Set video state 

Update display with logical video buffer 

Write character attribute string 

Write character string 

Write character string with attribute 

Replicate attribute 

Replicate cell 

Replicate character 

Write TTY string 
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To supplement OS/2 screen switching support, a DOS mode applica- 
tion can be written to use the EGA Register Interface. See "EGA Reg- 
ister Interface" on page 9-102. Alternately, a DOS mode application 
can be notified on a screen switch via Multiplex Interrupt 2FH, 
AH=40H. 

Note: On an IBM Personal System/2'™ or an IBM Personal Computer 
AT with the IBM Personal System/2™ Display Adapter, the registers 
on the adapter are both readable and writable. For these configura- 
tions, OS/2 reads and saves the registers on a screen switch away 
from DOS mode and restores the registers upon return to DOS mode. 

OS/2 issues a new Multiplex Interrupt (INT 2FH) to signal the fol- 
lowing two events: moving the DOS mode application to the bacl<- 
ground (AX=4001H) and moving the DOS mode application to the 
foreground (AX=4002H). A DOS mode application that wishes to 
receive this signal must "hook" the Multiplex Interrupt vector. That 
is, when the application is started, it must save the current INT 2FH 
vector and set the INT 2FH vector to point to the application's own 
interrupt handler. 

When the notification is received, the application must save all regis- 
ters, perform whatever processing is required, restore all registers, 
and issue the IRET instruction to return to OS/2. Only the following 
forms of processing are supported: 

• Modifying application and/or video memory, 

• Issuing ROM BIOS video service calls (INT 10H), 

• Issuing EGA Register Interface calls (INT 10H), and 

• Programming the EGA video card directly. 

Note: If an application moving to the background uses the EGA Reg- 
ister Interface to save the EGA registers, these registers are restored 
automatically when the application is returned to the foreground. 

An application may receive notification that it is moving to back- 
ground at any time. At the point this notification occurs, the applica- 
tion (other than its INT 2FH handler) is frozen until it is returned to the 
foreground. Code sequences that are sensitive to interruption can be 
protected with CLI/STI. 

When an application's INT 2FH handler receives notification with a 
value in AH other than 40H, the application must issue the JMP FAR 
instruction to branch to the previous INT 2FH vector. 
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Keyboard I/O Services 

Keyboard I/O Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 
The keyboard I/O function calls are summarized as follows: 



Binary Versus ASCII I/O 

A user process performs I/O to a character device in either binary or 
ASCII modes. These modes are set by the user process through the 
lOCtI facility. In binary mode, data is transferred exactly as it 
appears and for the data length that the user requested. In ASCII 
mode, data can be edited, and/or translated by OS/2. The operations 
that OS/2 performs for ASCII mode I/O are listed below. 



KbdCharIn 

KbdClose 

KbdDeRegister 

KbdFlushBuffer 

KbdFreeFocus 

KbdGetCp 

KbdGetFocus 

KbdGetStatus 

KbdOpen 

KbdPeeIc 

KbdRegister 

KbdSetCp 

KbdSetCustXt 

KbdSetFgnd 

KbdSetStatus 

KbdStrlngIn 

KbdSynch 

KbdXIate 



Read character, scan code 

Close a logical keyboard 

Deregister keyboard subsystem 

Clear the keystroke buffer 

Free the previous physical to logical bind 

Get loaded translate table IDs 

Bind the physical keyboard to a logical keyboard 

Get keyboard status 

Open a logical keyboard 

Peek at a character 

Register keyboard subsystem 

Set the translate table 

Install custom translate table 

Set foreground keyboard priority 

Set keyboard status 

Read character string 

Synchronize keyboard access 

Translate scan code 
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For a read in ASCII mode: 



• A caret C") is a symbol meaning: press the Ctrl key. 
The following characters preceded with a caret (^): 
''C, ''Break, ''S, ''P, and ^PrtSc are handled specially. 

• The data Is read until the first M or ENTER key is seen. This 
means that the length of the read data can be less than the 
requested length. Note that the data is always terminated with 
the byte sequence ODH OAH. 

• If ""Z is encountered, no further data is read. 

• Data will echo to the standard output device (screen) only if echo 
mode is ON. 

• Tabs are expanded Into 8-character boundary spaces upon echo, 
but left as 09H In the buffer. 

For an ASCII mode write: 

• The ''S is interpreted for flow control. 

• The P or PrtSc toggles printer echoing. 

• The ^C or ^ Break generates a signal for control-break handling. 

Note: The type ahead buffer Is flushed for control-break but not 
for '^C. 

• Tabs are expanded to 8-character boundaries and filled with 
spaces. 

• ASCII character codes less than 20H are preceded with a caret 

) and 40H is added to the codes. 

""T and ""U are not included in order to support certain foreign 
currency symbols. 

• Output is performed up to (but not including) a ""Z or the length of 
the request. The number actually written can be less than the 
number requested. 

A user process performs I/O to a block device strictly in binary mode. 
Data is transferred without interpretation or translation. 
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Mouse I/O Services 



Mouse I/O Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 
The mouse I/O function calls are summarized as follows: 



MouCiose 

IMouDeReglster 

IMouDrawPtr 

MouFlushQue 

IMouGetDevStatus 

IMouGetEventMasIc 

IMouGetNumButtons 
MouGetNumMlclceys 
MouGetNumQueEl 

MouGetPtrPos 

IMouGetPtrShape 

l\/louGetScaleFact 

MoulnltReal 
MouOpen 

IMouReadEventQue 
MouRegister 
IMouRemovePtr 
M ouSetDevStatus 
MouSetEventMask 

MouSetPtrPos 
IMouSetPtrShape 
MouSetScaieFact 
MouSynch 



Closes the mouse device for the current 
session. 

Deregister mouse subsystem 

Release screen area for device driver use 

Flush mouse event queue 

Query current mouse device driver status flags 

Query current mouse device 1 word event 

mask 

Query number of buttons 
Query number of miclceys per centimeter 
Query current status for the mouse device 
event queue 

Query current pointer position 

Query pointer shape and size 

Query scale factors for the current mouse 

device 

Initialize DOS Mode pointer draw 
Opens the mouse device for the current 
session 

Read the mouse device event queue 

Register mouse subsystem 

Reserve screen area for application use 

Set mouse device driver status flags 

Assign new event mask to the current mouse 

device 

Set current pointer position 

Set pointer shape and size 

Set scale factors for the current mouse device 

Get synchronous access 
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DOS Mode INT 33H Mouse API 



OS/2 supports a subset of the Microsoft®* DOS INT 33H mouse API. 

The Microsoft INT 33H mouse API is available only to those applica- 
tions executing in the DOS mode. OS/2 mode applications must use 
the mouse API device interface. 



See "DOS Mode INT 33H Mouse API" on page 9-61 for a detailed 
description of the DOS mode INT 33H function calls. 



The DOS mode INT 33H Mouse API I/O function calls are summarized 
as follows: 

Mouse Installed flag and reset 
Show mouse pointer 
Hide mouse pointer 

Get mouse pointer position and button status 
Set mouse pointer position 
Get button press information 
Get button release information 
Set minimum and maximum horizontal position 
Set minimum and maximum vertical position 
Set graphics pointer shape 
Set text pointer shape 
Read mouse motion counters 
Set user-defined subroutine input mask 
Light pen emulation on 
Light pen emulation off 
Set mickey/pixel ratio 
Conditional off 
Set double speed threshold 
Swap user-defined subroutine 
Query save mouse state storage requirements 
Save mouse driver state 
Restore mouse driver state 



33H- 


■ Function 


0 


33H 


■ Function 


1 


33H 


■ Function 


2 


33H- 


• Function 


3 


33H - 


■ Function 


4 


33H- 


■ Function 


5 


33H- 


• Function 


6 


33H- 


• Function 


7 


33H- 


■ Function 


8 


33H- 


■ Function 


9 


33H. 


- Function 


10 


33H- 


• Function 


11 


33H- 


• Function 


12 


33H 


■ Function 


13 


33H- 


- Function 


14 


33H- 


■ Function 


15 


33H- 


■ Function 


16 


33H- 


• Function 


19 


33H- 


• Function 


20 


33H- 


■ Function 


21 


33H- 


■ Function 


22 


33H- 


• Function 


23 



4 Microsoft Is a registered trademark of Microsoft Corporation 
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Device Monitor Services 



Character Device Monitors 

Character Device Monitors pi'ovide a mechanism for applications or 
subsystems to monitor all characters passing through a device driver. 
This mechanism allows any registered process to remove, insert or 
modify the information passing through the device. 

The OS/2 monitor mechanism consists of the OS/2 monitor calls and 
the monitor dispatcher device helper. The monitor calls provide the 
interface for the monitor to interact with the device driver and the 
monitor's own Input/output data buffers. The monitor dispatcher 
device helper handles the interfaces for the device driver and the 
mechanics of passing data from the output buffer of one monitor to 
the Input buffer of the next monitor In the chain. 
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Monitor Details 



Monitor 

DosMonOpen 

DosMonReg 

DosMonClose 



Thread{s) 



DosMonRead 
DosMonWrite 











In 




Out 



Monitor 

DosMonOpen 

DosMonReg 

DosMonClose 



Thread(s) 



DosMonRead 
DosMonWrite 



In 



Out 



Monitor Dispatcher 



DevHip MonitorCreate 
DevHIp Register 
DevHIp Deregister 



OPEN 



REGISTER 
(lOCTL) 



DevHIp 
MonWrite 
MonFlush 



(Notify 
Call) 



Device Driver 



CLOSE 



Deregister 



Monitor Processes 

A character device monitor is an application process, or part of an 
application process; that is, It runs at protection level 3 using 
standard OS/2 function calls (DosMonXXX) to interact with the device 
driver and the monitor's own input and output data buffers. 

For a process to gain access to a device driver's data stream for 
character monitoring, the monitor must do the following: 

1. Issue the DosMonOpen call to establish a connection to the 
device driver for monitors. DosMonOpen gets a device handle 
that will be used in subsequent OosMonReg and DosMonClose 
calls. 

2. Issue the DosMonReg call to register a pair of input and output 
buffers with the device driver and monitor dispatcher. After the 
monitor is installed in the monitor chain, the monitor dispatcher 
automatically moves data between monitors (if there is more than 
one in the chain) and between the last monitor In the chain and 
the device driver's monitor chain buffer. 

The device handle for monitors returned from a DosMonOpen call is 
unique to that process. A process needs to call DosMonOpen only 
once per character device whose data stream(s) it wishes to monitor, 
if a process issues more than one DosMonOpen call to the same 
device, the same device handle will be returned. A process may then 
register one or more monitors on the same device handle for moni- 
tors. 

Note: Until the monitor returns successfully from the DosMonReg 
call, no characters will enter the monitor's input buffer. It is the appli- 
cation's responsibility to synchronize completion of the DosMonReg 
call and the subsequent monitoring of the data stream with device 
input into the data stream. See the diagrams on pages 6-51 and 6-52 
for examples. 



( 
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After a monitor has gained access to tlie data stream, it may remove, 
Insert, modify or view ali characters in data records passing through 
the data stream by: 

1. issuing the DosMonRead call to move a data record from its input 
buffer to a private data area that the monitor process can access 
freely, and 

2. Issuing the DosMonWrite call to move a data record from the 
monitor process private buffer into its output buffer. 

A data record is defined minimally as a WORD containing flags mean- 
ingful to the monitors and devices whose data stream they are moni- 
toring. The flag WORD is always the first WORD in the data record. A 
monitor can modify the data record received on the last DosMonRead 
call before calling DosMonWrite to return it to the device's data 
stream. However, because the character device driver is sensitive to 
these flags and to the entire data record, the monitor application 
should never alter this order within a data record and must conform 
to device driver "rules" on filtering data records. Refer to Chapter 9, 
Device Drivers for device-specific descriptions of flag WORDs and 
data records. 

Data movement from the monitor's input buffer (DosMonRead) and 
into the monitor's output buffer (DosMonWrite) is synchronized with 
the device driver and monitor dispatcher. When a data record is 
moved into the monitor's input buffer, the monitor process is signaled 
by the monitor dispatcher that a data record is available for 
DosMonRead. When DosMonRead completes movement of one data 
record, the monitor dispatcher is signalled that a data record has 
been removed and there is now more room for new data records. 
The opposite is true for DosMonWrite. 

Note: Monitors get control of all data in a data stream before an 
application can read it. Therefore, a monitor's processing must be 
fast, performing no I/O or semaphore waits. For example, there is no 
recovery if a monitor application does a read for a character from the 
device driver API buffer when it has not yet moved the character 
through its input and output buffers into the device driver monitor 
chain buffer. Complex processing in a monitor should be performed 
within a monitor thread separate from that which makes 
DosMonRead and DosMonWrite calls. 
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When a process no longer wishes to monitor a character device's 
data stream, it relinquishes its access to the data streams by calling 
DosMonClose. DosMonClose is issued with a specific opened device 
handle for monitors, as returned from a previous DosMonOpen. All 
monitors for the current process that registered using this handle 
(those monitoring the particular character device) are terminated. 



Pseudo code for a simple keystroke monitor is: 

**1t****1t*******************1e****1e**1e**1c** 

SIMPLE CHARACTER DEVICE MONITOR 
***************************************** 



CALL DosSetPrty ;Set this monitor's thread 
; priority high 

; GET ACCESS TO THE DEVICE'S DATA STREAM 

CALL DosMonOpen ;get a device handle for monitors for 
; the application 

CALL DosMonReg ; register a pair of input and output 

; buffers as a monitor 

WHILE [we want to monitor the data stream] 

CALL DosMonRead ;read a data record from the monitor's 
; input buffer 

; process, or filter, the data record (keystroke) 

CALL DosMonWrite ; write a filtered data record into the 
;moni tor's output buffer 



END WHILE 



CALL DosMonClose ; close all monitors from this 

;appli cation registered on the same 
: device handle 
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Below Is a diagram that shows how monitors fit into the system struc- 
ture and how OS/2 supports these functions. 

There are three interfaces in this diagram. They are labeled: 

1. Program to device driver Interface 

2. Device driver to monitor dispatcher Interface 

3. Monitor dispatcher to monitor process interface 




Programs 



KERNEL 



Device Driver 



□ 



Buffers (B) 



Monitor 

Dispatcher 

(DevHelp) 

(A) 



(3) 

Buffer 
Updates 

DataFlow 
Control Flow 



Interfaces 

1. Program to device driver 

This interface establishes a monitor connection and tears it down. 
This is the registration process. 

• Open: DosMonOpen gets a handle to use for monitor registra- 
tion. 

• Registration: DosMonReg registers monitor and data buffers. 

• Deregistration/Close: DosMonCiose deregisters the monitor. 
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2. Device driver to monitor dispatcher 

This interface is provided with DevHip routines to do the 
following: 

• MonitorCreate: Creates a chain of monitors. 

• Register: Adds a monitor to a chain. 

• Deregister: Removes a monitor from a chain. 

• MonWrite: Passes data records to a monitor. 

• MonFlush: Removes data from the monitor chain. 

3. Monitor dispatcher to monitor process 

The monitor dispatcher coordinates movement of data between 
the device driver and monitor input/output buffers. 



Module Description 

• (A) Monitor Dispatcher: This pacl<age is common to all device 
drivers and serves the device drivers and the monitors in user 
space. 

• (B) Monitor Buffer Management: Applications are responsible for 
allocating their own monitor buffers, and setting the first WORD of 
each buffer equal to the length of the buffer. The monitor dis- 
patcher starts and manages all buffers for registered monitors. 



Device Monitor Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The device monitor function calls are summarized as follows: 

DosMonOpen Open a connection to an OS/2 device monitor. 

DoslMonClose Close a connection to an OS/2 device monitor. 

DosMonReg Register a set of buffers as a monitor. 

Dosll/ionRead Read data from a monitor structure. 

Dosl\/lonWrite Write data to a monitor structure. 
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Monitor Data Structures 

The monitor data structures consist of buffers and data records. 

Tlie monitor API and monitor dispatcher device helper routines 
manage the buffers for monitor applications. Applications registering 
monitors are required to provide the length (number of bytes) of the 
buffer in the first WORD of each buffer, length WORD included. 
Thereafter, the application must not corrupt the buffer at any time. 

Since more than one monitor from more than one process may be 
registered as monitoring the same data stream, a minimum buffer 
length must be defined to maintain data movement through all 
buffers. The monitor dispatcher defines this minimum buffer length 
as the length of the device driver's monitor chain buffer plus 20 bytes. 
The length of a monitor's input and output buffers must be at least 
this length. This is also the recommended length of the private data 
area specified on a DosMonRead call. 

In/Out Buffers specified on DosMonReg: 



Field 


Size 


Length 


2 Bytes 


Used by Monitor Dispatcher 


18 Bytes 


Must be > = Length of device driver monitor 
chain buffer plus 20 Bytes 




Device driver monitor chain buffer specified on DevHIp 
MonitorCreate: 


Field 


Size 


Length 


2 Bytes 


Max read/write record size 





Refer to pages 9-59, 9-93, and 9-155 for device driver specific informa- 
tion. 
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Device Monitor Record 



Only one data record can be read (DosMonRead) or written 
(DosMonWrite) at a time. Data records In any given input or output 
buffer may be of different lengths. 

Because the minimum buffer size for all buffers in a monitor chain is 
defined in terms of the device driver's monitor chain buffer, the 
maximum size of a data record is also defined in terms of this buffer's 
size. A monitor application cannot write (DosMonWrite) into its 
output buffer a data record whose length is greater than the length of 
the device driver monitor chain buffer minus two bytes. 

The first WORD of a data record is a flag word. A data record may 
consist of only a flag word. The flags are defined as follows: 



Monitor Flags 

ByteO 



7 


6 


5 


4 


3 


2 


1 


0 



^ Open 



Close 

Flush 

Reserved 

Reserved 

Reserved 

Reserved 



Reserved 



Byte 1 



6 5 



1 0 



Device Driver 
Dependent 



Flushing a data stream is an important operation. All data must be 
cleaned out of the data stream at certain times. At these times, a 
flush record will be placed in the data stream by the device driver by 
a DevHlp_MonWrite and must pass through all monitors In the chain 
to allow them to reset their internal states. The flush record will force 
them to flush all internal buffers. Placement of new data records into 
the chain by way of a DevHlp_MonWrite will be suspended until the 
flush record reaches the device driver's input buffer. Therefore, flush 
records must not be consumed by the monitor. 
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When an application receives a data record witli an open or close bit, 
the action to be talcen depends on the issuing device driver. Refer to 
Chapter 9, "Device Drivers" on page 9-1 for device driver specific 
information. 



Data Flow Through a Monitor 



Monitor Y 



Monitor Z 



Thread(s) 



Thread(s) 



(4) 



In 



Out 



(3) 



(6) 



(8) 



(9) 



In 



Out 



(7) 



Monitor Dispatcher 



DevHIp MonitorCreate 
DevHIp Register 
DevHIp Deregister 



OPEN 



REGISTER 
(lOCTL) 

CLOSE — 



DevHIp 
MonWrite 
MonFlush 
(2) 



(10) 



Device 
Driver (1) 



Device Driver Monitor Buffer 

(11) 

API Buffer 



Deregister 



1. The device driver receives the data and decides to which chain, if 
any, to direct it. 

2. A monitor is registered with the chain. The device driver calls 
DevHlp_MonWrite (monitor dispatcher device helper routine) to 
place the data into the chain's first buffer, allocated by the 
monitor dispatcher when the monitor chain is created. 
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3. The monitor dispatcher automatically moves the data record from 
the chain's first buffer into the input buffer of the first monitor in 
the chain (Monitor Y). 

4. Registered Monitor Y calls DosMonRead to get a data record 
from the data stream and place it into its private data area. 

5. After filtering the data record, registered Monitor Y returns the it 
to the data stream by calling DosMonWrite to write the data 
record into its output buffer. 

6. The monitor dispatcher automatically moves the data record from 
the output buffer of Monitor Y Into a monitor dispatcher data area. 

7. The monitor dispatcher automatically moves the data record from 
the monitor dispatcher data area Into the input buffer of the next 
monitor in the chain, Monitor Z. 

8. Registered Monitor Z calls DosMonRead to get a data record 
from the data stream and place it into its private data area. 

9. After filtering the data record, registered Monitor Z returns it to 
the data stream by calling DosMonWrite to write the data record 
into its output buffer. 

10. The monitor dispatcher automatically moves the data record from 
the output buffer of Monitor Z into the device driver's monitor 
chain buffer. 

11. The device driver moves the data from the device driver's 
monitor chain buffer into its API buffer, where it is ready to be 
read by an application. 
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The Time Window of Monitor Registration 

An application that requires monitoring all characters passing 
through a device, including those received by the device from the 
time the application is invoiced through the time the monitor is regis- 
tered and has gained access to the data stream, must do some addi- 
tional work. (For example, the case of type-ahead characters.) The 
diagram on page 6-52 illustrates the time window between invocation 
and completion of monitor registration when characters received by 
the device are placed Into the device's API buffer until monitor regis- 
tration is completed. Monitor registration is completed when charac- 
ters received by the device are then placed into the monitor chain. 
The following pseudo code suggests a possible solution for such an 
application: 

;OUR APPLICATION WISHES TO MONITOR ALL CHARACTERS TO A 
; DEVICE, INCLUDING TYPE-AHEAD CHARACTERS 

; APPLICATION IS RUNNING 

; If no other monitors registered for this chain, data 
; to device is being written to device's API buffer 

CALL DosMonOpen ;get handle to the device 

;We want to monitor all data received by the device since 
; the application was invoked, including type-ahead data 

CALL DosMonReg ; register a monitor with the data stream 

;If DosMonReg returns no error, then data to device 
; is being written to monitor chain (i.e. the input 
; buffer of the first monitor in the chain) 

IF [DosMonReg returned without error] 
THEN 

;The device driver will start placing data received from 
; the device into the monitor chain. The monitor 
; dispatcher will start moving data into the input buffer 
; of the first monitor in the chain. 
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; Before the DosMonRead/DosMonWrite thread is started, we 
; want to look at any type-ahead data that was received 
; by the device BEFORE completion of monitor registration 
; and make it available to another application. 
; First, get any type-ahead data 

WHILE [device's API buffer is not empty] 

Get a character from the API buffer through the 
Device Subsystem Call 

Place it in a temporary buffer 
END WHILE 

;Now, make it available to another application by placing it 
; back in the device's data stream through our monitor's 
; output buffer. 

WHILE [temporary buffer is not empty] 

Get a character from the temporary buffer 

Build a device-specific monitor record 

CALL DosMonWrite ; return it to the device's data 
; stream and, therefore, to the 
; API buffer for another app 

END WHILE 

; Begin monitoring data stream - we may want to do this on 
: a separate thread 

WHILE [we want to monitor data stream] 

CALL DosMonRead ;get a data record from data stream 
; process the data 

CALL DosMonWrite ;return the data to the data stream 
END WHILE 

CALL DosMonClose ; close all monitors from this process 

; registered on the same device handle 

ENDIF 
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Hints for Using Monitors 



Some common problems occur in OS/2 monitor applications because 
of failure to follow the guidelines outlined earlier. 

1. The monitor Input and output buffers specified when you call 
DosMonReg should be defined separately, but within the same 
segment. These buffers should be at least as large as the device 
driver's monitor chain buffer plus 20 bytes. The first WORD of 
each buffer should include the length of the buffer in bytes, length 
WORD inclusive. If the buffers are incorrectly specified, 
DosMonReg will return an error. 

2. A monitor process should be written so the thread(s) that actually 
read and write the monitor data run at the lowest time-critical pri- 
ority. They should never perform operations such as I/O or 
semaphore waits that might delay them. The monitor process 
can have other thread(s) running at normal priorities to handle 
such things. 

3. Complex processing should be done in threads separate from 
your monitor (DosMonRead/DosMonWrite) threads. If not, the 
processing may block the device's data stream. For example, an 
application running in the same session may never receive data 
on a read if complex processing is not done separately. 

4. The monitor should not consume flush records but, should return 
them to the data stream by calling DosMonWrite. If the flush 
records are not returned, the monitor is blocking the data stream 
and the device driver may send a "buffer full" signal. For 
example, in the case of the keyboard, a beep will sound. 

5. Threads in your application should not poll the device's API 
buffer to ensure it is never time slicing or yielding so that other 
threads may run. If polling is done in this fashion, threads will 
not run, data will not reach the device driver's API buffer, and 
applications will not find any data available when doing a read. 
This may cause the system to stop running. 

6. A single process can register more than monitors. In addition, 
the process can distribute these monitors on different chains. 
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Providing Monitor Support in a Character Device Driver 

A character device driver may define more tlian one data stream for 
its device. Eacli data stream may be monitored by a "cliain" of one 
or more registered device monitors. Some devices drivers, sucli as 
the l<ey board and the mouse, may define their data streams on a per 
session basis. Other device drivers, such as the printer, may define 
their data streams on a per device basis. 

When an OS/2 character device driver receives data from its device, 
the driver decides where to direct it, that is, into which of its data 
streams the driver will place the data. For example, when the l<ey- 
board device driver receives a keystrol<e from the l^ey board, it directs 
that l<eystrol<e into the data stream for the current active session. 

A character device monitor is an application or part of an application 
that uses standard OS/2 function calls to interact with the device 
driver to gain access to one of its data streams for monitoring or fil- 
tering all data passing through the device. 

In order for an application to monitor data passing through a char- 
acter device, the character device driver must provide monitor 
support. 



6-46 



A device driver must include in its DATA segment: 

1. A buffer in which to build the data record placed into the monitor 
chain on a DevHIp MonWrite call. 

DS:SI (on calling DevHip MonWrite) is the address of the data 
record to be placed into the monitor chain. DS must point to the 
device driver's data segment when DevlHip MonWrite is called. 

2. For each data stream that can be monitored by a chain of moni- 
tors, a "monitor chain buffer" that will receive filtered data from 
the chain of monitors; that is, from the output buffer of the last 
monitor in the chain. 

The first WORD of each monitor chain buffer must first (for 
example, before calling DevHIp MonitorCreate) contain the 
LENGTH of the buffer (length word Inclusive). The length of a 
monitor chain buffer will define: 

a. The minimum size of ail buffers that are part of the monitor 
chain; that is, the length of each of the input and output 
buffers of all monitors that register with the chain must be 
greater than or equal to the length of the device driver 
monitor chain buffer plus 20 bytes. 

b. The maximum size of a data record placed into the chain of 
monitor buffers (that is, the length of the device driver buffer 
minus 2 bytes). See diagram on page 6-50. 

A device driver must include in Its CODE segment: 

1. A NOTIFICATION routine that is called by the monitor dispatcher 
when the monitor dispatcher has placed a single 'filtered' data 
record that has passed through the entire monitor chain into the 
monitor chain buffer. The device driver must process this data 
record before returning to the monitor dispatcher; for example, 
make it available to device subsystem calls by moving it into the 
API buffer. 

When the NOTIFICATION routine has been called by the monitor 
dispatcher, 

a. the first WORD of the monitor chain buffer contains the length 
(length word inclusive) of the filtered data record. See 
diagram on page 6-50. 

b. DS points to the device driver's data segment and ES:SI 
points to the device driver's monitor chain buffer. 
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For each data stream that can be monitored by a chain of monitors a 
device driver must define for the monitor dispatcher the location 
(addresses) of the notification routine and the monitor chain buffer by 
calling DevlHip MonltorCreate: 

1. The monitor dispatcher assigns a handle to the chain of monitors 
for the data strearn. The device driver will use this handle when 
Instructing the monitor dispatcher to perform device helper func- 
tions on the chairi of monitors (that is, DevHIp Register, DevHIp 
MonWrite, DevHIp MonFlush, and DevHIp Dereglster). 

2. The device driver may call DevHIp MonltorCreate any time prior 
to issuing other monitor dispatcher device helper functions: 

a. When the device is loaded; 

b. In response to an 'open' request, if DevHIp MonltorCreate 
has not been previously called to define the monitor chain; or 

c. In response to a 'register' request, if DevHIp MonltorCreate 
has not been previously called to define the monitor chain, 
and before DevHIp Register is caljed. 

A device driver must handle open, register, and close requests for 
monitors, 

1. When an application calls DosMonOpen to get a handle to the 
device for monitors, an open request Is sent to the device driver. 
In response, a device driver may define a monitor chain for the 
data stream by calling DevHIp MonltorCreate, If it has not previ- 
ously done so. 

2. When an application calls DosMonReg to register a pair of buffers 
as part of the chain of monitors for a specified data stream (see 
DosMonReg INDEX parameter in Technical Reference, Vol. 2) for 
a device, a register request is sent to the device drjver. In 
response, the device driver: 

a. May call DevHIp MonltorCreate to define the monitor chain, if 
It has not previously done. 

b. Uses the handle returned from a previous DevHIp 
MonltorCreate call and calls DevHIp Register, to direct the 
monitor dispatcher to Insert the buffers into the chain of mon- 
itors for the specified data stream. 

For each monitor chain handle, the device driver should track 
the number of monitors it registered with the monitor chain. 
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3. When an application calls DosMonClose to ternfiinate monitoring 
data passing through a device, a 'close' request is sent to the 
device driver. In response, the device driver: 

a. Must call DevHIp Deregister for each monitor chain handle 
for monitors currently registered. This directs the monitor 
dispatcher to remove all buffers associated with the process 
that issued the DosMonClose from the chain of monitors for 
the data stream. 

Note: A single process may register monitors for more than 
one data stream for a device. For example, a process may 
register a keystroke monitor for each session. 

b. May call for a monitor chain on return from each DevHIp 
Deregister. If there are no monitors registered In the monitor 
chain, call DevHIp MonltorCreate with the "remove chain" 
option to remove the monitor chain's definition from the 
monitor dispatcher's knowledge. 

When monitors are registered in a chain of monitors for a device driv- 
er's data stream, the device driver must place data received from the 
device into the chain of monitors so that it can be "filtered." The 
device driver builds a data record in Its data segment and calls 
DevHIp MonWrite to write that record Into the Input buffer of the first 
monitor in the monitor chain for the data stream. See page 6-52 for a 
detailed description. 

When a chain of monitors for a device driver's data stream is empty 
(that is, a chain has been defined via a DevHIp MonitorCreate call, 
but no monitors have been previously registered), the device driver 
may use its monitor support to place a data record directly into its 
monitor chain buffer by calling DevHIp MonWrite. The monitor dis- 
patcher automatically will call the device driver's notification routine 
to move the data record into the device driver's API buffer. See page 
6-51 for a detailed description. 

When a device driver needs to guarantee that all data has been 
cleaned out of the chain of monitors for a data stream, it issues a 
DevHIp MonFlush call to direct the monitor dispatcher to place a spe- 
cially marked record, a FLUSH record, into the chain of monitors for 
the data stream. This record must pass through all monitors in the 
chain; therefore, all monitors In the chain that receive a FLUSH 
record on a DosMonRead must return it to the monitor chain on a 
DosMonWrite. No new data records will be placed into the monitor 
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chain until the FLUSH record reaches the device driver's monitor 
chain buffer. 

The following diagram shows a device driver monitor chain buffer 
before a data record is placed into It by the monitor dispatcher. 

Length 
Word 

XX I 

XX BYTES ► 

The following diagram shows a device driver monitor chain buffer 
after a data record is placed into it by the monitor dispatcher. The YY 
length is less than or equal to the length of the device driver monitor 
chain buffer as initially defined. 

Length 
Word 

YY I 

YY BYTES 
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The following diagram shows data movement through a character 
device driver before monitor registration: 



To Application 



Character 
Device 



READ character 
thru subsystem 
call 



Character 
Device Driver 



Notification 
Routine 



Monitor Chain 
Buffer 

API Buffer 



(1a) 



(2) 



(1b) 



Note: No monitors are installed. 



Data received by the device by an INT or a write passes through the 
device driver to its API buffer. The device driver has an option to do 
this by either: 

1. Using the existing device driver monitor support to: 

a. Write the data into the Monitor Chain buffer using DevHIp 
MonWrite and let the monitor dispatcher automatically call 
the device driver's notification routine (to signal the device 
driver that data has been written into this buffer); 

b. Let the device driver's notification routine move the data into 
its API buffer. 

2. Writing the data directly into its API buffer. 
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The following diagram shows data movement through a character 
device driver during and after monitor registration: 



To Application 



Character 
Device 



READ character 
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call 
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Monitor Chain 
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Monitor 
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1. A process issues a DosMonReg call to register a monitor with a 
character device. Until the monitor registration process has com- 
pleted successfully, data is written into the device driver's API 
buffer. 

2. Once the monitor registration process has completed success- 
fully, 

a. Data is placed into the monitor chain by the device driver 
using DevHIp MonWrite. 

b. After the data has passed thru the monitor using 
DosMonRead/DosMonWrite calls, the monitor dispatcher 
moves the data into the device driver's monitor chain buffer 
and calls the device driver's notification routine to signal it 
that data has been placed into this buffer. 

c. The device driver moves the data from Its monitor chain 
buffer into its API buffer. 
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Keystroke Monitor Interface 



Some applications monitor all keystrokes and provide global system 
function before more conventional applications receive the key- 
strokes. Examples include national language support for switcliing 
the keyboard layout and for Asian language input conversion. Other 
examples are applications which provide a desk calculator or key- 
stroke macro expansion. Hardware enforced protection requires that 
the system provide interfaces for such applications, which run as 
processes. 
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This diagram depicts tlie l<eyboard device keystrol<e monitor inter- 
face. The l(eystrol<e monitors have been previously enrolled as moni- 
tors. A monitor can pass the keystroke through, consume the 
keystroke, or replace the keystroke with one or many keystrokes. 

Keystroke Monitor Interface Diagram 
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Threads responsible for moving keystroke data through a monitor 
chain must pay special attention to the thread priority. Keystroke 
monitor threads must execute within the time critical priority class. 
See Technical Reference, Vol. 2 description of DosMonReg for more 
details concerning keystroke monitor priority. 
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Printer/Spooler Services 

The printer/spooler is structured as shown in the diagram below: 
Printer/Spooler Structure 
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Printer 



The data flow shown In the printer/spooler structure above is: 

1. This flow is the normal API to the printer. 

The Application program issues DosOpen, followed by "n" 
DosWrites/DoslOCtIs to the printer. The file system sends an 
Open request paclcet to the printer device driver, followed by an 
Activate Font lOCtl. The Application program's DosWrites go to 
the printer device driver until a DosClose is issued. 

2. This flow is from the printer device driver to the spooler through 
the DosMonRead monitor interface. 
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The printer device driver sends an Open command buffer, fol- 
lowed by an Activate Font monitor command buffer, and tlien "n" 
buffers corresponding to the DosWrites. 

3. This flow is by a Call interface to the Font Switcher dynamic link 
routine. 

a. This occurs when the Activate Font, Query Active Font, or 
Verify Font command buffer is received by the spooler from 
the printer device driver. 

b. Escape sequence data and/or font data necessary to cause 
the printer to perform the actual code page and font switch is 
written to the temporary spool file by the Font Switcher. The 
data is treated by the spooler as part of, and in sequence 
with, the data being printed by the application program. 

4. This flow is the return from the call described in the flow previ- 
ously. 

5. This flow shows data being written by the spooler to a temporary 
spool file using DosWrites. This is the data sent by the applica- 
tion program to be printed. 

6. The spooler reads data from its temporary spool files on the disk, 
in sequence based on its spool queues, using DosReads. 

7. The spooler sends data to the device driver to be printed. 

a. If the spooled printer is a parallel device, the spooler sends 
the data back to the printer device driver in a monitor buffer 
using Monitor Index 1 for the DosMonWrite. 

b. If the spooled printer is an ASYNC device, the spooler sends 
the data back to the ASYNC device driver using the DosWrite 
function Interface. 

c. If the data to be returned is a Font Monitor Buffer Response, 
the spooler sends the response back to the printer device In a 
monitor buffer using Monitor Index 2 for DosMonWrite. 

8. The device driver sends data to the printer through the hardware 
adapter. 

a. The printer device driver sends the data to parallel printers. 

b. The ASYNC device driver sends the data to serial printers. 
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Spooler Monitor 



DOS Mode Force Output to Printer 

The print spooler spools the printer output until a DosClose is issued. 
When printing from the DOS mode, many applications use the INT17 
Interface which does not require DosOpen/DosClose. In this case, 
the printer output is spooled until the program exits. The user may 
press Ctrl-Alt-PrtSc (while the DOS mode is in the foreground) to 
force printed output to be printed from DOS mode applications. 

Spooler Operational Description 

The Spooler uses a dynamic link module called the Font Switcher to 
perform the code page and font switching. 

initialization: When the Spooler is invoked by the user (user 
command SPOOL), it accesses the system data structure which con- 
tains the code page and font information provided by the DEVINFO 
command In CONFIG.SYS. If DEVINFO is present for the specified 
printer name (LPTx) in the code page and font data structure, the 
spooler will call the DosPFSInIt entry point of the Font Switcher 
dynamic link module to initialize font switching. After the Spooler 
and Font Switcher have completed Initialization, print spooling along 
with code page and font switching are enabled for the specified 
printer. 

if the DEVINFO code page and font Information are not present in the 
code page and font data structure maintained by the system for the 
specified printer name, the spooler completes its initialization without 
initializing the Font Switcher for the specified printer. In this case 
spooling is enabled for the specified printer, however, code page and 
font switching are not. 

Activate Font: When an Activate Font - Font Monitor Buffer Command 
is received by the spooler for a specific System File Number, the 
spooler calls the DosPFSActivate entry point of the Font Switcher. 
The Font Switcher changes the active code page and font for the 
System File Number(/handle), and uses the font file to cause the code 
page and font switch to occur. The code page and font switch occurs 
in one of the following ways depending on the font support provided 
by the target printer: 
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1. If the specified font is contained in the printer hardware (ROM or 
cartridge, as specified by the DEVINFO command CONFIG.SYS), 
the Font Switcher writes the escape sequence required to switch 
the printer to this hardware font directly Into the temporary spool 
file. The escape sequence necessary to perform this switch is 
available for the Font Switcher in the font file specified for the 
printer. 

2. If the specified font Is not contained In the printer hardware, and 
the printer allows multiple downloadable fonts, the Font Switcher 
will write the following Information directly Into the temporary 
spool file In the following order: 

a. The escape sequence required to cause the font data that 
follows to be loaded Into the correct printer buffer; 

b. The font information; 

c. The escape sequence required to cause the printer to use the 
buffer just loaded. 

If the Activate Font command specifies a font which has been pre- 
viously loaded into a font buffer other than the one which Is cur- 
rently active, the Font Switcher writes the escape sequence 
required to switch the printer to the desired font buffer directly 
into the temporary spool file. 

All escape sequences and font information required are available 
for the Font Switcher In the font file specified for the printer. 

3. If the specified font Is not contained in printer hardware, and the 
printer allows a single font to be downloaded, the Font Switcher 
will write the following Information directly into the temporary 
spool file In the following order: 

a. The escape sequence required to cause the font data that 
follows to be loaded Into the correct printer buffer; 

b. The font information; 

c. The escape sequence required to cause the printer to use the 
buffer. 

All escape sequences and font Information required are available 
for the Font Switcher in the font file specified for the printer. 
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Query Active Font: When a Query Active Font - Font Monitor Buffer 
Command is received by the spooler for a specific System File 
Number, the spooler calls the DosPFSQueryAct entry point of the Font 
Switcher. The DosPFSQueryAct function returns the active code page 
and font for the specified System File Number(/handle) to the spooler. 
The spooler returns the information to the printer device driver using 
the Query Active Font Font Monitor Buffer Response. The printer 
device driver then returns the information to the Query Active Font 
lOCtI caller. 



Verify Font: When a Verify Font - Font Monitor Buffer Command is 
received by the spooler for a specific System File Number, the 
spooler calls the DosPFS Verify Font entry point of the Font Switcher. 
The DosPFSVerifyFont function returns whether the specified code 
page and font is available for the specified printer. 



Spooier Monitor interfaces 



The interfaces required by the spooler for code page and font 
switching are: 

• System code page and font Information 

• Font Monitor Buffer Commands 

- Activate Font 

- Query Active Font 

- Verify Font 

• Font Switcher function calls are summarized as follows: 

DosPFSInit Initialize code page and font 

DosPFSActivate Activate Font 

DosPFSQueryAct Query Active Font 

DosPFSVerifyFont Verify Font 

DosPFSCIoseUser Close Font User Instance 

For function call details, refer to Technical Reference, Vol. 2. 

• Printer Font File Format 

These interfaces are described in the following sections. 



System Code Page information: The spooler must be able to access 
the System Code Page Information when it is invoked (user command 
SPOOL) from some system provided data segment. The information 
required is that provided by the CONFIG.SYS command DEVINFO. 
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This information includes tlie printer name, printer type, code page 
and fonts provided in tlie printer hardware and the path name of the 
font file to be used. 

Font Monitor Buffer Commands: The Font Monitor Buffer Commands 
which provide the code page and font switch interface between the 
printer device driver and the spooler monitor are: 

1. Activate Font 

2. Query Active Font 

3. Verify Font 

These commands and their responses are described in detail in "Font 
Monitor Buffer Commands" on page 9-159. 

Printer Font Fiie Format: Each printer for which code page and font 
switching is supported must have a font file which describes: 

• Control Sequences for downloading and switching fonts 

• Font definitions 

OS/2 Font Fiie Format 

The format of the OS/2 Font File is shown in the following diagram: 



Character Set 
File Header 

Control Sequence 
Definitions 



Character Set 
Definition Block 1 

Character Set 
Definition Block 2 



Character Set 
Definition Block n 



The Font File Header defines the printer which the font file supports 
and has pointers to the Control Sequence Definitions section of the 
file and to the first Font Definition Block. The Font Definition Blocks 
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are a linked list throughout the rest of the file. Each of these sections 
of the font file are described In more detail below: 

Font File Header 

The format of the font file header is shown in the following diagram: 



00 


Font File Type Number 


02 


Printer Type 


OA 


Version Major Number 


OB 


Version Minor Number 


OC 


Number of Hardware Fonts 


OD 


Number of RAM Fonts 


OE 


Control Sequence BIk Ptr 


10 


Character Set Def BIk Ptr 


14 


Reserved 




(46 Bytes) 



The definition of each field is as follows: 

Font File Type Number This field identifies the format version or type 
of the font file. The value for the format specified for OS/2 is 
4554h. 

Printer Type This field is eight bytes which specify the printer type 
which this font file supports. 

Version A/laJor Number This byte is the "major" version number of the 
font file. 

Version iMInor Number This byte is the "minor" version number of the 
font file. 

Number of Hardware Fonts This byte specifies the maximum number 
of hardware fonts (ROM or cartridge slots) which this printer 
supports. 

Number of RAA/I Fonts This byte specifies the maximum number of 
fonts which this printer may have downloaded to it simultane- 
ously. 
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Control Sequence BIk Ptr This WORD pointer Is the offset from the 
beginning of the file at which the Control Sequence Definition 
Section begins. 

Character Set Def BIk Ptr This DWORD pointer is the offset from the 
beginning of the file at which the first Font Definition Block 
begins. 

if this value Is zero (0), there are no font definition blocks in this 
file. 

Reserved This area of 46 bytes is reserved and should be set to zero 
(0). 

Control Sequence Definitions: The following diagram shows the 
format of the font file control sequence definition section: 



CSD Section Size 



Reserved 



No. Hdw Font Select Ptrs 
Hdw Font seq 0 pointer 



Hdw Font seq n Pointer 
No. RAM CSD Pointer Biks 
RAM CSD Pointer BIk 1 
RAM CSD Pointer BIk 2 



RAM CSD Pointer Bll< n 

Control Sequence 
strings 



The definition of each field is as follows: 

CSD Section Size Control Section Definition Section Size - This 

WORD gives the total size in bytes of the CSD Section (including 
itself) 

Reserved This area is reserved and must be set to zero. 

No. Hdw Font Select Ptrs This Word specifies the number of l-iardware 
Font Select Sequence DWORD pointers which follow. 
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Hdw Font Select x ptr Each DWORD pointer in tlie Hardware Font 
Select Sequence Table points to the beginning of a length pre- 
fixed control sequence string which is in the "Control Sequence 
Strings" area of this section. 

The first control sequence corresponds to the control sequence 
command for "Select Hardware Font 0", the second control 
sequence is for "Select Hardware Font 1", and so on. Hardware 
Font 0 corresponds to the hardware default font of the printer. 

For printer type 5202 only, the control sequences do not corre- 
spond to hardware fonts except for the first control sequence 
which is necessary to select the hardware font when both code 
page and font id are zero. If the printer type is 5202, the font file 
is for a printer with plug-in cartridge fonts and the hardware font 
select sequences are to select a cartridge code page, font id, 
pitch, and whether proportional spacing is used. These items 
are dynamically inserted into the control string at runtime. 

When an Activate Font command is specified with both the OS/2 
values set to zero, then Hardware Font 0 Is selected. 

Each pointer Is an absolute DWORD offset from the beginning of 
the file. 

No. RAM CSD Pointer BIks This Word specifies the number of RAM 
Font Buffer Control Sequence Definition Pointer Blocks (RAM 
CSD Pointer BIk) which follow. 

RAM CSD Pointer BIk x The RAM Font Buffer CSD Pointer Blocks are 
an array in which each element (block) contains the control 
sequences which correspond to a font buffer in the printer. The 
order of the blocks correspond to the RAM font buffer number 
(that is the first block corresponds to the first font buffer, and so 
on). Each pointer in a RAM CSD Pointer Block Is an absolute 
DWORD offset from the beginning of the file to length prefixed 
control sequence strings contained In the "Control Sequence 
Strings" area of this section. Any pointer which is zero (0) indi- 
cates that the corresponding control sequence is not defined. 
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RAM Font Buffer CSD Pointer Block Format 

Each RAM CSD Pointer Block has the following format: 



00 


Select Buffer Seq Ptr 


04 


Begin Download Seq Ptr 


08 


End Download Seq Rr 


OC 


Reserved 




(20) Bytes) 



Select Buffer Seq Ptr The Select Buffer Sequence DWORD pointer 
points to the beginning of a length prefixed control sequence 
string which is in the "Control Sequence Strings" area of this 
section. This control sequence is used to "select" (or make 
active) the font buffer. This pointer is an absolute offset from 
the beginning of the file. 

Begin Download Seq Ptr The Begin Font Download Sequence DWORD 
pointer points to the beginning of a length prefixed control 
sequence string which is in the "Control Sequence Strings" 
area of this section. This control sequence specifies that a font 
download for a particular font buffer follows. This pointer is an 
absolute offset from the beginning of the file. 

End Download Seq Ptr The End Font Download Sequence DWORD 
pointer points to the beginning of a length prefixed control 
sequence string which is in the "Control Sequence Strings" 
area of this section. This control sequence specifies that a font 
download for a particular font buffer is complete. This pointer is 
an absolute offset from the beginning of the file. 

Reserved Each RAM Font Buffer CSD Pointer block contains a 
reserved area of 20 bytes which must be set to zero (0). 

Control Sequence Strings This area of the section contains the actual 
length prefixed control sequence strings pointed to by the 
pointers described above. The first byte of each string indicates 
the length of the string in bytes. 
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If the printer type is 5202, tliere are dynamic inserts for car- 
tridge code page, font id, pitcli, and proportional spacing. 
These inserts are made at the following positions of the control 
string (starting counting with one): 

Byte Description 

9 High order byte of code page 

10 Low order byte of code page 

16 High order byte of font ID 

17 Low order byte of font ID 

18 High order byte of pitch (1/1440 inches) 

19 Low order byte of pitch (1/1440 inches) 

20 Proportional spacing on/off 

Value Description 

0 = Wild card 

1 = Use fixed pitch 

2 = Proportional 
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Font Definition Block 

Each font definition block witliin the file has the following format: 



00 


Pointer to Next Block 


04 


Code Page Number 


06 


Font Id Number 


08 


Length of Font Data 


OA 


Reserved 


20 


Font Definition Data 



The definition of each field is as follows: 

Pointer to Next Block This DWORD pointer points to the next font defi- 
nition block in the file. 

A value of zero (0) indicates that this is the last font definition 
block in the file. This pointer is an absolute offset from the 
beginning of the file. 

Code Page Number This is the Code Page number of the font defi- 
nition contained within this block. 

Font Id Number This is the Font Id number of the font definition con- 
tained within this block. 

Note: The code page number and font id should not both be 
zero because this indicates the default hardware OS/2. If both 
are zero, the font will not be selected. 

Length of Font Data This is the number of bytes in the "Font Definition 
Data" area. 

Reserved These bytes are reserved, and must be set to zero (0). 

Font Definition Data This area contains the bytes which are sent to 
the printer when downloading a particular font. 
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Chapter 7. OS/2 Device Driver Architecture 



Device drivers written for DOS are synclironous and often non- 
interrupt driven. Because DOS is a single-tasl< operating system, tliis 
presents no problem. A program cannot proceed until tlie I/O has 
been completed, so it is acceptable for the device driver to hold the 
CPU until the I/O is complete. 

OS/2, on the other hand, is a multitasking operating system. It must 
be able to assign the CPU to tasks that are not waiting for I/O. There- 
fore, device drivers written for OS/2 must surrender the CPU while 
they are waiting for I/O completion. Consequently, OS/2 device 
drivers must be interrupt-drlven. 

In addition, OS/2 provides a DOS mode to support DOS applications. 
Consequently, OS/2 device drivers must support device I/O requests 
in the DOS mode. This means that OS/2 device drivers must handle 
I/O requests issued by the applications running in the DOS mode and 
may need to interlock DOS mode ROM BIOS device I/O with OS/2 
mode device I/O. Performance considerations also require that 
device drivers be able to handle hardware interrupts without the 
overhead of a mode changing method. OS/2 device drivers must 
therefore be bimodal, that is, execute in both the OS/2 mode and the 
DOS mode. 

The basic characteristics of the OS/2 device driver are: 

• Support of a multitasking environment 

• Execution in both the DOS mode and the OS/2 mode 
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Types of Device Drivers 



There are two types of device drivers: 

• Character device drivers 

• Blocl< device drivers 

Character device drivers manage I/O on character-oriented devices. 
These devices perform I/O on a character-by-character basis. A 
character device has a name like SCREENS, KBD$, LPT1, or C0M1. 
A character device driver can support more than one device by 
having multiple linked device headers where each header indicates a 
different name. 

Block device drivers support block-oriented devices. These devices 
perform I/O on a block of data, typically through DMA (Direct Memory 
Access). Applications request I/O on block-oriented devices via a file 
system. Consequently, block device drivers do not have names. 
Instead, a block device driver is assigned one or more drive letters. 
A block device driver can support multiple devices (or units), so a 
drive letter is assigned for each unit (or device). A block device 
driver specifies the number of devices that it supports when it is 
called to initialize. Refer to the INIT device command, "OH / INIT ini- 
tialize Device" on page 7-43. 

The order in which the block device drivers appear in the 
CONFIG.SYS configuration file (via the DEVICE = command) deter- 
mines the order in which they receive drive letters. 
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Application I/O to Devices 



An application accesses a device driver when it performs an I/O 
request. There are tliree l<inds of interfaces that provide access to 
device drivers: 

• File system interface 

• Subsystem interface 

• lOCtI interface 

The File system interface consists of the file I/O function calls. OS/2 
applications use the DOS dynamic link calls for file I/O, DOS applica- 
tions use the DOS dynamic linl< calls fertile I/O, and DOS applications 
running in the DOS mode issue INT 21 H File I/O function calls. The 
file I/O function calls are used primarily to perform I/O on block 
devices like fixed disks. Some file I/O function calls can be used to 
perform I/O on character devices. These calls include: 

• DosOpen 

• DosClose 

• DosRead 

• DosReadAsync 

• DosWrite 

• DosWriteAsync 

The advantage of using the file I/O function calls to perform I/O on a 
character device is that the application can redirect the I/O. The 
application performs I/O to a handle (file or device) which it obtained 
from opening the named resource passed to It. 

A subsystem interface shields an application from having to manage 
device I/O. The file system is an example of a subsystem. The file 
system allows the application to view a file as a logical sequence of 
sectors, thus shielding the application from having to manage the 
physical locations of the data on the disk media. Other subsystem 
examples include the VIO, KBD, and MOU subsystems which provide 
I/O services for video, keyboard, and mouse devices respectively. 

The lOCtI interface is the mechanism that an application or sub- 
system uses to send device-specific control commands to the device 
driver. The lOCtI mechanism is DosDevlOCtI for new applications 
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and the INT 21 H lOCtI request for DOS applications. I/O commands 
can be sent to both block and character device drivers. The applica- 
tion or subsystem must first obtain the device handle by doing an 
open on the device name. 

I/O Support For The DOS Mode 

A device driver is responsible for managing I/O for its device. 
Because many devices must be accessible from both the DOS mode 
and the OS/2 mode, an OS/2 device driver must manage its device 
across both modes of operation. Examples of such cross-mode 
devices are disk, keyboard, screen, mouse and printer. 

Device I/O in the DOS mode is performed in one of three ways: 

• DOS INT 21 H interface 

• ROM BIOS interface 

• Direct access to the device 

I/O using the DOS INT 21H interface is transformed into the request 
packet interface, which the device driver receives. (Similarly, I/O 
using the OS/2 dynamic link function calls are transformed into the 
request packet interface.) Because the request packet interface is 
standard across modes for new device drivers, it poses no problem 
for the device driver in managing its device. 

I/O using the ROM BIOS poses some problems for an OS/2 device 
driver. The OS/2 device driver must intercept the ROM BIOS soft- 
ware interrupt (by setting the vector with the DevHIp SetROM Vector — 
see "SetROMVector Set DOS Mode Software Interrupt Vector" on 
page 8-78) and interlock ROM BIOS operations on its device in two 
ways: 

• Serialize access to the device. 

Serialize by using semaphores to indicate when the device is 
busy with a request (and consequently cannot accept/tolerate a 
request from ROM BIOS). 

• Protect critical sections of ROM BIOS execution from suspension. 

Suspension occurs when a user switches away from the applica- 
tion in the DOS mode to an application in the OS/2 mode. This 
causes the DOS mode to be suspended in the background. 
However, some I/O processing cannot tolerate being suspended. 
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Specific examples are the printer (BIOS INT 17H), 6\sk (BIOS INT 
13H), and screen (BIOS INT 10H). It is the responsibility of the 
OS/2 device driver to intercept the appropriate ROM BIOS Inter- 
rupt and issue the DevHIp function call, ROMCritSection, to 
protect the ROM BIOS critical section of execution. 

Note: When the OS/2 device driver Issues ROMCritSection to 
enter a ROM BIOS critical section, the user is not able to switch 
away from the application In the DOS mode to an application in 
the OS/2 mode. This poses potential problems for the user. For 
example, if a DOS mode terminate-and-stay resident program 
takes control while the CPU is executing the ROM BIOS, the time 
spent in the ROM BIOS critical section will be longer. The worst 
case Is that the terminate-and-stay resident application is interac- 
tive, never allowing the OS/2 device driver to issue the exit from 
critical section and never allowing the user to switch away from 
the application in the DOS mode until the user terminates the 
application. 

Application I/O using direct access to a device driver's device poses 
the same problem for the device driver under OS/2 as it does to a 
device driver operating under DOS. If device state information is crit- 
ical or if device I/O must be serialized, then a device driver can 
choose not to access the full function of the device. Control of the 
device, in this case, would be shared between the application and the 
device driver. 

Components of a Device Driver 

An OS/2 device driver contains one or more of the following 
components: 

• Strategy Routine 

The strategy routine is called to handle I/O requests through a 
request packet interface with the OS/2 kernel. The strategy 
routine executes at task-time as a result of an application I/O 
request. Because application I/O requests can come from new 
OS/2 applications running in the OS/2 mode and DOS applica- 
tions running in the DOS mode, the strategy routine must not 
have a dependency on the mode in which it is invoked. 

The strategy routine follows the FAR CALL/RET model. When it 
is done processing, it performs a FAR RET to the kernel. By con- 
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vention, the strategy routine does not need to save and restore 
any registers it uses, because tlie preservation of registers is 
fiandled by tlie kernel. 

Tlie request packet interface is discussed in the section "Request 
Packets" on page 7-37. 

• Hardware Interrupt Handler 

The hardware interrupt handler is called as the result of a hard- 
ware interrupt and executes at interrupt time. For performance 
reasons the hardware interrupt handler must not have a depend- 
ency on the mode in which it Is invoked. 

The hardware Interrupt handler follows the FAR CALL/RET 
model. When it has completed processing, it performs a FAR 
RET to the kernel. In addition, it must set or clear the CF (Carry 
Flag) to indicate whether or not it owns the interrupt. By conven- 
tion, the hardware interrupt handler does not need to save and 
restore any registers it uses. This is done by the kernel before 
calling the device driver. 

• Timer Handler 

The timer handler is called as the result of a periodic clock tick 
and executes at interrupt time. The timer handler manages time- 
outs and is similar to the INT 1CH user timer feature of ROM 
BIOS. The timer handler must not have a dependency on the 
mode in which it is invoked. 

The timer handler follows the FAR CALL/RET model. When it has 
completed processing, it performs a FAR RET to the kernel. The 
timer handler must save and restore any registers it uses. 

• Software Interrupt Handler 

The software interrupt handler is called directly by a software 
Interrupt. Software interrupts can only be Issued in the DOS 
mode, so the software interrupt handler executes only in the DOS 
mode. Typically, the software interrupt handler is used to inter- 
cept ROM BIOS software interrupts to serialize device access 
between the protect mode and the real mode; or to prevent the 
BIOS service from being suspended when the user attempts to 
switch away from the DOS mode application to an OS/2 mode 
application. 
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OS/2 Device Driver Contexts 



There are four contexts (modes) in which OS/2 device drivers 
operate. They are: 

• Kernel Mode 



The OS/2 kernel calls the device driver strategy routine for task- 
time operations. (Task-time is a generic term that refers to exe- 
cuting code as a thread within a process.) The strategy routine 
will execute as a thread within a process. The strategy routine 
will not be preempted by a task switch but may be interrupted by 
incoming hardware interrupts. Kernel mode applies to both the 
DOS mode and the OS/2 mode. 

• Interrupt Mode 



The OS/2 kernel calls the device driver interrupt-time compo- 
nents, the hardware interrupt handler, and the timer handler. 
(Interrupt-time is a generic term that refers to executing code as 
a result of an interrupt; the thread of execution does not belong to 
a process.) The hardware interrupt handler and the timer 
handler will not execute code as a thread belonging to a thread 
specific process; the thread of execution results from a hardware 
interrupt. Interrupt mode applies to both the DOS mode and the 
OS/2 mode. 

• User Mode 



In user mode the device driver software interrupt handler is 
called, and applies only to the DOS mode. The software interrupt 
handler is invoked by a software interrupt. In this mode, the 
device driver software interrupt handler may be preempted by a 
task switch. 

• INITMode 



in INIT mode the device driver strategy routine is called with a 
request packet containing the INIT command. The initialization 
code runs in the OS/2 mode at the application privilege level with 
I/O privilege. A limited set of dynamic link function calls are 
available for use, as well as a portion of the device helper 
(DevHIp) function calls. This is discussed in the section "Device 
Driver Initialization" on page 7-26. 



7-7 



OS/2 Device Driver Operations 



To show the interaction between the strategy routine and the hard- 
ware interrupt handler in the processing of an I/O request, the fol- 
lowing example is presented. 

The handling of an I/O request begins with OS/2 calling the strategy 
routine entry point with a request pacl<et. The strategy routine checks 
the validity of the I/O request. If the request is valid, the strategy 
routine may place the request on a work queue for the device, using 
the DevHIp functions for request queue management. 

If the device is currently idle, the strategy routine starts the request at 
the device. The strategy routine may then wait for the device driver 
interrupt by suspending its thread of execution with the DevHIp func- 
tion BLOCK. 

When the device interrupt occurs, the hardware interrupt handler 
checks the request to see if it has been completed. If the request has 
not been completed, the hardware Interrupt handler continues the 
request at the device. If the request has been completed, the hard- 
ware interrupt handler sets the return status in the request packet. 
The hardware interrupt handler may remove the completed request 
packet from the work queue and start the next request at the device. 
If the strategy routine is waiting for the device Interrupt, (which is 
blocked), then the hardware interrupt handler can wake up the 
strategy routine with the DevHIp RUN. 

In this example, the strategy routine queues the requests and only 
initiates the I/O if the device has been inactive; the hardware inter- 
rupt handler starts requests as they reach the head of the work 
queue. The thread context, in which the device driver determines 
that a particular request is complete, is not necessarily the same 
thread context in which the device driver received the request. This 
is particularly true for the interrupt-time components of the device 
driver. For example, the address of a user buffer passed to the 
device driver when the request was issued belongs to a specific LDT, 
which may not be the current LDT when the request ends. The device 
driver can accommodate this by storing the buffer address as a 32-bit 
physical address. 

The device driver strategy routine is called by OS/2 with a pointer to 
the request packet. The pointer to the request packet is bimodal: in 
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other words, the pointer is valid in both the DOS mode and the OS/2 
mode. Any addresses passed in the request packets for read/write 
requests are passed as 32-bit physical addresses (normalized). 
Therefore, the device driver does not need to lock or convert the 
addresses into physical addresses. The device driver only needs to 
lock addresses that it receives from a source other than OS/2, such 
as in the case of a process passing an address via a generic lOCtl. 

The multitasking environment dictates that the components of the 
device driver must be capable of handling requests simultaneously. 
This means that the components of the device must relinquish exe- 
cution whenever possible. The device driver relinquishes control at 
task-time by BLOCKING, YIELDING, or referencing a segment which 
had been swapped out; OS/2 will not preempt a thread in the device 
driver. However, once the device driver releases its execution, OS/2 
can call the device driver with a new request. In other words, once 
the strategy routine BLOCKS, YIELDS, or references a swapped-out 
segment, its thread of execution can be called with a new request 
under the context of a different thread. 

While the strategy routine can assume that it will not be preempted 
by other task-time instances, it must protect itself against its own 
interrupt-time components. It should disable interrupts when 
checking if the device is active and when examining the device 
queue. The interrupt-time components will only be preempted by 
other higher priority interrupts. 

One component of the device driver may be preempted, the software 
interrupt handler. The software interrupt handler is invoked by a soft- 
ware interrupt in the DOS mode. It can be preempted by background 
OS/2 mode threads which are scheduled to execute and which may 
issue I/O requests causing other components of the device driver to 
be invoked. 

Request Packet Queue Management 

The strategy routine can either queue a request packet or process it 
immediately. Typically, only read requests and write requests need 
to be queued because the device is busy. Other types of requests 
can usually be handled immediately by the strategy routine. 

A block device driver such as the disk device driver, can process 
queued requests in any order. For instance, the block device driver 
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can choose to sort the requests to optimize device access time. A 
character device driver must always handle queued requests in the 
order it received them; otherwise, mixed output could result. 

The request packet queue is really a linked list. The request packet 
contains a linkage field which allows the packets to be chained 
together. 

The device driver can manage its work queue of request packets with 
the DevHIp functions for Request Queue Management. 

In order to use the Request Queue Management DevHIp services, the 
device driver must allocate a DWORD variable as a queue header, 
with one queue header per queue. The DWORD variable must be ini- 
tialized to zero to indicate an empty linked list or the end of the linked 
list. 

The DevHIp services use the queue header to identify a specific 
linked list of request packets and will set the header to the first 
request packet in the list. The linkage field in the request packet is 
then used to chain the request packet to another request packet. 

Because the pointer to the request packet is bimodal (valid in both 
the DOS mode and the OS/2 mode), the device driver can manipulate 
the linkage fields in the request packets itself by using its own linked 
list management. 

Memory Management 

The device driver must manage addressability to data across task 
time and interrupt time operations. DevHIp services are provided to 
allow the device driver to be independent of the CPU mode, whether 
at task-time or interrupt-time. Addressability is particularly critical at 
interrupt-time because the context of the current process may not 
cover the address space containing the data buffer that the hardware 
interrupt handler needs to access in order to move data. 

To prevent an application from passing an unauthorized address, the 
device driver can use the DevHIp service Verify Access to validate the 
application's authority to access the memory. Because device 
drivers execute at the operating system privilege level, they have 
access rights to segments at all privilege levels. However, a well- 
balanced device driver must not allow an application to force the 
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device driver into accessing segments which the application does not 
own. This check applies to addresses that an application passes 
within a generic lOCtI request; the OS/2 Icernel validates addresses 
for READ and WRITE requests. If an application passes a bad 
address to the device driver, the device driver could halt the system if 
it does not verify the caller's access authority. Once an address has 
been verified, the device driver can proceed with the I/O request. 

The DevHIp services LOCK and UNLOCK are used to fix in place a 
segment, which prevents the segment from being moved or swapped 
while the device driver needs access to it. The device driver does not 
need to locl< segments for the READ or WRITE request pacl<ets. 
However, segments referenced in the generic lOCtI request packet 
will need to be locked by the device driver if it intends to access them 
at interrupt time. 

Once a segment has been locked, the device driver can convert the 
virtual address (segment/selectoroffset) into a physical address with 
the DevHIp VirtToPhys for later use at interrupt time. 

The DevHIps AllocPhys and FreePhys allow the device driver to get 
and free a fixed amount of memory. The device driver must use the 
DevHIps PhysToVirt and UnPhysToVirt to obtain a virtual address 
(segment/selector:offset) to access the memory. 

The device driver should choose to locate critical data structures or 
data transfer areas in its data segment. This is optimal for perform- 
ance when access to the structures or buffers must take place at both 
task time and interrupt time. 

Semaphore Management 

There are two kinds of semaphores, RAM semaphores and system 
semaphores. RAM semaphores are defined by the semaphore user 
by allocating a DWORD variable and using the address in place of the 
handle in DevHIp semaphore services. OS/2 provides no resource 
management on RAM semaphores (such as releasing the semaphore 
when the owner terminates). System semaphores are created by an 
application through a dynamic link function call. OS/2 provides full 
resource management on system semaphores, including releasing of 
the semaphore and notification when the owner of the semaphore ter- 
minates. 
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Typically, a device driver creates and uses RAM semaphores to 
control operations among its components. They are not restricted for 
use by mode. The device driver may use RAM semaphores while 
executing in user mode. 

System semaphores are typically used by a device driver to commu- 
nicate to an application process. A device driver cannot create a 
system semaphore; although it can use the system semaphore that 
the application process has created. The application process must 
pass the application's handle to the device driver in a generic iOCtl. 
The device driver then uses the DevHIp service SemHandle to obtain 
a semaphore handle that the device driver can use. The device 
driver must indicate in the SemHandle call that the system 
semaphore is IN-USE by the device driver. When the device driver no 
longer needs to use the system semaphore to communicate with the 
application, it must call the DevHIp SemHandle and specify that the 
system semaphore is NOT-IN-USE. 



Character Queue Management 



Character queues are used by character device drivers to buffer data. 
The two most frequently used structures for character buffers are the i 
FIFO and the CIRCULAR buffer. 



A character device driver may use the DevHIp services to manage a 
simple circular buffer for characters. The DevHIp services operate on 
the following character queue header. 



CharQueue STRUC 

Qsize DW 
Qchrout DW 
Qcount DW 
Qbase DB 

CharQueue ENDS 



? ; Size of buffer in bytes 

? ; Index to next char out 

? ; Count of characters in buffer 

? : Start of buffer 



Prior to using the character queue DevHIp services, a device driver 
must allocate the queue header and initialize the Qsize field. The 
DevHIp Queuelnit must be called before calling any of the other char- 
acter queue DevHIps. The other fields in the queue header are 
managed by the character queue DevHIps and do not need to be 
examined or altered by the device driver. 

A character device driver is not required to use the character queue 
DevHIp services. A character device driver can define its own char- 
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acter buffer management, tailored to the requirements of its buffer 
structure. 

Hardware Interrupt Management 

The device driver's hardware interrupt handler is the component of 
the device driver which deals with a hardware interrupt. The hard- 
ware interrupt handler is called by the OS/2 kernel when the hard- 
ware interrupt occurs, therefore it must follow the FAR CALL/RET 
model. By convention, the hardware interrupt handler does not need 
to save and restore any registers it uses. This is done by the kernel. 
For performance reasons, the hardware interrupt handler will be 
called in the CPU mode that the hardware interrupt occurred. There- 
fore, the Hardware Interrupt Handler must not have a dependency on 
the mode in which it is invoked. 

Before the hardware interrupt handler can be invoked, its entry point 
must be registered for a specific hardware interrupt. This may be 
done during or after device driver initialization with the DevHIp 
service SetlRQ. Once the call to the DevHIp has been made, the 
hardware interrupt handler can be Invoked. 

Hardware interrupt sharing is not supported on the Personal Com- 
puter AT or the Personal Computer XT Model 286 A hardware inter- 
rupt level (IRQ) that is shared among two or more devices is referred 
to as a shared interrupt. Interrupt sharing is an extension of a 
device's design. A single interrupt level (IRQ) can be shared among 
two or more devices if the devices are specifically built for interrupt 
sharing. A device driver cannot share the hardware interrupt level 
without cooperation from its device. This is true for both edge- 
triggered and level-sensitive interrupt environments. 

In an edge-triggered interrupt environment, an interrupt request will 
be recognized by the 8259 Programmable Interrupt Controller (PIC) 
as a particular edge transition (like low-to-high) on the hardware 
interrupt request line. The interrupt request line can remain level 
without generating another interrupt. The 8259 PIC requires an End- 
Of-lnterrupt (EOl) and another of the same kind of edge transition to 
recognize an interrupt on that interrupt level. 

In a level-sensitive Interrupt environment, an interrupt request will be 
recognized by the 8259 PIC as a particular level on the hardware 
interrupt request line. The interrupt condition must be removed 
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before the EOl is issued or else the 8259 will continue to generate 
interrupts for that interrupt level. 

Note: OS/2 supports interrupt sharing only on the PS/2, which pro- 
vides a level-sensitive interrupt environment, where multiple device 
drivers (devices) may share a particular hardware interrupt. On both 
the Personal Computer AT and the Personal Computer XT Model 286, 
hardware interrupts cannot be shared among multiple deyice drivers 
(devices). 

The basic model for managing a hardware interrupt follovvs: 

1. The device driver must register an interrupt handler for a hard- 
ware interrupt, specifying whether the device driver intends to 
share the interrupt level. 

2. When invoiced, the device driver interrupt handler tests the device 
to see if it generated the interrupt. 

3. If the device has an interrupt pending or caused a spurious inter- 
rupt, the interrupt handler owns the processing of the Interrupt. 

The interrupt handler services the device, resets the interrupting 
condition at the device, issues the End-Of-lnterrupt (EOl) with the 
DevHIp service EOl, and RET FAR with the indicator that it owned 
the interrupt (CF = 0). 

4. If the device does not have an interrupt pending, the interrupt 
handler does not own processing of the interrupt. 

The interrupt handler must RET FAR with the indicator that it 
does not own the interrupt (CF = 1). 

To permit two or more device drivers to share an interrupt level, each 
device driver must adhere to the following rules: 

1. Interrupt Level Sharing 

All interrupt levels have the potential to be shared. There are 
some restrictions. 

SYSTEM TIMER RULE The system timer interrupt level (IRQ 0) 
cannot be shared. 

The system timer interrupt level is owned by a DOS mode 
interrupt handler for compatibility operations. 
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ILL-BEHAVED DEVICE RULE An interrupt handler for an ill- 
behaved device must not share an interrupt level. 

An ill-behaved device is one that generates interrupts 
before its interrupt handler is installed or is one that cannot 
be told to stop generating interrupts. 

Well-behaved devices are devices that do not power-up with 
interrupts pending and do not remain active after their han- 
dlers have terminated. Also, well-behaved devices do not 
usually generate spurious interrupts. 

BIOS INT HANDLER RULE A bi modal interrupt handler that uses 
the BIOS interrupt handler to support interrupt processing 
from I/O generated by the DOS mode must not share an 
interrupt level. 

A BIOS interrupt handler does not share its interrupt level, 
but assumes that it owns the interrupt processing. 

2. Initializing the Interrupt Vector 

SET IRQ RULE The device driver must indicate when signing up 
for a hardware interrupt level with the DevHIp SetlRQ that it 
will share the Interrupt. 

IRQ ENFORCEMENT RULE If a device driver signs up for a hard- 
ware interrupt indicating that it will not share it, then a sub- 
sequent SetlRQ request to share that hardware interrupt 
will be refused. Conversely, if a device driver signs up for a 
hardware interrupt indicating that it will share it, then a sub- 
sequent SetlRQ request to exclusively own the hardware 
interrupt will be refused. 

DOS MODE SHARING RULE Interrupt sharing cannot be per- 
formed by a DOS mode interrupt handler. 

A hardware interrupt is owned either by one or more 
bimodal interrupt handlers (OS/2 device drivers) or by a 
single DOS mode interrupt handler. 

A DOS mode interrupt handler exclusively owns its hard- 
ware interrupt. It may not share its interrupt with a bimodal 
device driver. A DOS mode interrupt handler may not share 
its interrupt because, as part of the DOS mode, it can 
execute only when the DOS mode Is In the foreground. 



7-15 



COROLLARY If a bi modal device driver (OS/2 device driver) owns 
a device that is accessible from a BIOS software interrupt, 
the bimodal device driver's interrupt handler will own the 
hardware interrupt level, not BIOS. However, the bimodal 
device driver may NOT share Its interrupt level with other 
bimodal device drivers, if the bimodal interrupt handler 
uses the BIOS interrupt handler when processing an inter- 
rupt generated by an I/O request from the DOS mode. 

The bimodal device driver's interrupt handler may need to 
support DOS mode I/O by using the BIOS interrupt handler 
in the DOS mode. In this case, the bimodal device driver 
must be aware that the BIOS interrupt processing does not 
include a check for ownership of the interrupt level. In addi- 
tion, the bimodal device driver must be aware of the back- 
ground processing of OS/2 mode processes while the DOS 
mode Is in the foreground — the bimodal device driver is 
always called in the current processor mode of operation. 

IRQ MASK RULE The operating system owns the masking of the 
hardware Interrupt at the 8259 interrupt controller. 

The operating system will enable the hardware Interrupt at 
the 8259 interrupt controller when the first interrupt handler 
signs up for the hardware interrupt. This permits the inter- 
rupt handler to communicate with its device during initial- 
ization. 

3. Processing The Interrupt 

STI ENTRY RULE Interrupt handlers that share interrupts will be 
entered with processor interrupts enabled. 

This is to prevent the lockout of higher priority hardware 
interrupts, because the search for the owner of the current 
interrupt level takes a variable amount of time. 

Interrupt handlers that do not share interrupts will be 
entered with processor interrupts disabled. 

A COS mode interrupt handler will be entered with 
processor interrupts disabled for compatibility. 

IRQ OWNERSHIP RULE The device driver interrupt handler, when 
invoked, must always interrogate its device to see if its 
device caused the interrupt. If the Interrupt handler's 
device caused the interrupt, then the interrupt handler owns 
the processing of the interrupt. 
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If the interrupt handler owns the processing of the interrupt, 
It may briefly disable processor Interrupts for critical oper- 
ations. It must issue the EOl as soon as possible. 

The device driver interrupt handler must be aware that once 
it issues the EOl, it could be reentered at Its interrupt han- 
dler's entry point. 

If the interrupt handler's device did not cause the interrupt, 
then the interrupt handler must not issue an EOl. 

INT RETURN RULE The interrupt handler, after taking the appro- 
priate action in processing the interrupt, must return an 
Indication whether It claimed the interrupt or not. 

If the interrupt handler owns the interrupt, then it must clear 
the GARRY FLAG (CF = 0) and issue a FAR RET when proc- 
essing is complete. If the Interrupt handler does not own 
the interrupt, then it must set the CARRY FLAG (CF = 1) 
and issue a FAR RET. 

SEARCH RULE The operating system calls each interrupt handler 
registered for a particular interrupt level until one of the 
interrupt handlers claims the interrupt. 

EOl RULE Management of the 8259 interrupt controllers is the 
responsibility of the operating system. However, the End- 
Of-lnterrupt (EOl) is the responsibility of the interrupt 
handler. 

The interrupt handler must use the DevHIp EOl service to 
issue the EOl as soon as possible In the processing of its 
interrupt. This permits the 8259 interrupt controller to 
process other interrupt requests at the current interrupt pri- 
ority as well as interrupt requests of lower priorities. 

In a level-sensitive interrupt environment, the EOl must not 
be issued to the 8259 interrupt controller(s) until the inter- 
rupt condition at the device is removed. 
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Advanced BIOS requires that all ABIOS staged-on interrupt 
request blocks be processed for the LID that owns the Inter- 
rupt prior to the EOl. (Refer to the ABIOS EOl Placement 
Rule.) 

PhysToVirt RULE Selectors used for PhysToVirt represent a crit- 
ical resource; an Interrupt handler that uses PhysToVirt 
must not issue the EOl until after it no longer needs the 
addresses generated by PhysToVirt. Otherwise, the inter- 
rupt handler should disable processor Interrupts before 
Issuing the EOl; this will allow the interrupt handler to use 
the temporary selectors for its interrupt level without getting 
another interrupt on its level. 

POSITION RULE An Interrupt handler that shares an interrupt 
level must not depend on its position in the list of handlers 
for that interrupt level. 

4. Advanced BIOS Considerations For Interrupt Processing 

ABIOS REQUEST BLOCK RULE The interrupt handler for a partic- 
ular Logical ID (LID), when invoked by the operating 
system, must call Advanced BIOS for each ABIOS request 
block that is Incomplete-Waiting-On-lnterrupt, even if one of 
the request blocks gets the return indicator that the inter- 
rupt belongs to it. 

ABIOS EOl PLACEMENT RULE The EOl must be Issued after ail 
ABIOS staged-on interrupt request blocks have been proc- 
essed for the LID that owns the interrupt. 

ABIOS LID IRQ RULE Advanced BIOS defines one and only one 
interrupt level per LID. 

If a device driver handles more than one LID on the same 
interrupt level, then the device driver could choose to reg- 
ister only one interrupt handler for any LID on that level. In 
this case, the operating system will call the interrupt 
handler only once when the interrupt occurs; the interrupt 
handler must manage the processing of more than one LID 
in order to determine if it owns the interrupt processing for 
them. 

In this case, the device driver interrupt handler should be 
aware of the Fairness Criteria problem. A LID at the end of 
the Interrupt handler's list will not get as much service as a 
very active LID at the front of the list. 
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5. Spurious interrupts 

in an edge-triggered interrupt environment, to iiandie a spurious 
Interrupt, reset tlie interrupt at tiie 8259 interrupt controiler (EOl), 
issue the giobai rearm if sliaring interrupts, and enable processor 
interrupts. Generaily, tiiese actions would be taicen by the last 
interrupt handler in the list of interrupt handlers. 

In a level-sensitive interrupt environment, to handle a spurious 
interrupt, reset the interrupt condition at the device, issue the 
EOl, and enable processor interrupts. 

Advanced BIOS provides the capability to reset a spurious inter- 
rupt at the device through the use of an Advanced BIOS Default 
Interrupt Handler for the Logical ID (LID). The interrupt handler 
calls the Advanced BIOS Default Interrupt Handler for its LID if 
there are no outstanding Incomplete-Waiting-on-lnterrupt request 
blocics. The Advanced BIOS Default Interrupt Handler will indi- 
cate either that the interrupt condition was successfully reset or 
that the interrupt did not belong to the device referenced by the 
LID. In the case that the Advanced BIOS Default Interrupt 
Handler replies that the device was successfully reset then the 
interrupt handler must Issue the EOl and return as owning the 
Interrupt. 

For the case where there are Incomplete-Waiting-On-interrupt 
request blocks outstanding. Advanced BIOS keeps track of which 
interrupts are expected, and will automatically service a spurious 
interrupt when called by the interrupt handler. The Interrupt 
handler must call Advanced BIOS with each and every request 
block that Is Incomplete-Walting-On-lnterrupt for a LID even if the 
first one returns an indication that it performed some processing. 
The interrupt handler must be able to process the spurlous- 
Interrupt return code from any one of these calls to the Advanced 
BIOS Interrupt service. 

For a device driver that directly interfaces to the device, it must 
check the device for the interrupt condition, even If the Interrupt 
condition does not correspond to an outstanding I/O request. If 
the device had caused the spurious interrupt, the Interrupt 
handler must reset the interrupting condition at the device, Issue 
the EOl, and return as owning the interrupt. 

Note: If the device causing the spurious interrupt in the level- 
sensitive interrupt environment is not Identified and reset, then 
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the interrupt level is locked up. This is a feature of the 8259 inter- 
rupt controller operating in level-sensitive mode. 

6. DEINSTALL Considerations 

Refer to the section, "DEINSTALL Considerations" on page 7-64, 
for details. 

Notes: A single device driver with a single interrupt handler for a 
particular interrupt level may share its interrupt level among one or 
more devices that it owns. This case applies to devices of similar or 
same nature, for example, a printer device driver supporting more 
than one printer (adapter) on one interrupt level. For this case, the 
operating system will invoke the device driver's interrupt handler 
when the hardware interrupt occurs. The device driver's interrupt 
handler must determine which of its devices caused the interrupt; the 
interrupt handler will not get called for each device it manages. 

If the device driver is supporting multiple devices on the same hard- 
ware interrupt, it only needs to process the first device it discovers 
that was causing an interrupt on the interrupt level in question. 

Because of the level-sensitive interrupt environment, other devices 
that are requesting service will cause another interrupt to be gener- 
ated and the device driver would be re-entered at the same entry 
point. Because of this, the device driver should strategically place 
the EOl to allow an orderly processing of any re-entrant interrupt 
requests. 

However, if the device driver registers a separate unique interrupt 
handler entry point for each device it owns, with the interrupt han- 
dlers sharing the same interrupt level, then the device driver must 
adhere to the interrupt sharing rules. The operating system will 
invoke each interrupt handler, until one handler claims the interrupt. 
To the operating system, each registered interrupt handler entry point 
appears as a separate interrupt handler. This allows the device driv- 
er's interrupt handler(s) to be called for each device. 
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Device Driver Program IModel 

The program model for the OS/2 device driver is a small model. In 
other words, the device driver consists of two segments, a single 
code segment and a single data segment. The device driver execut- 
able image does not contain a stack segment; a stack is provided by 
the system. 

Because the device driver has only one code segment, it must not 
have any FAR CALLs or FAR JMPs internal to the code segment. The 
device driver does not need to examine the code segment value. 
OS/2 tracks the segment/selector and sets the proper value for the 
CPU mode in the OS register when It calls the device driver compo- 
nents. This applies to both task time and interrupt time. OS/2 tracks 
the data segment value in a similar fashion, and sets the proper value 
for the CPU mode In the DS register. 

The device driver loadable image may contain extra space in its data 
segment area to be referenced and extra code in its code segment 
area to be executed at initialization. Once the device driver has com- 
pleted initialization, only the primary areas of the code and data seg- 
ments will be kept. The extra space which is no longer needed, will 
be returned to the system. 

The file image of the device driver follows: 



EXE Header 

Device Driver 

Data 

Segment 

Data 



Code 

Code Segment 



The data segment must be the first segment after the .EXE file 
header. This allows the device header to be located immediately 
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after the .EXE file header because the device header is required to be 
located at the beginning of the file. 



Device Driver Header 

The device driver's data segment must contain a Device Header as 
the very first item. The Device Header has the following structure. 



Field 


Length 


Pointer To Next Header 


DWORD 


Device Attribute 


WORD 


Offset To Strategy Routine 


WORD 


Reserved 


WORD 


Name or Units 


8 BYTES 


Reserved 


8 BYTES 



Pointer to Next Device Header Field 

The pointer to the next header Is set by OS/2 at the time the device 
driver Is loaded. For loadable device drivers, this field should be set 
to -1. The pointer-to-next-header field is set by Syslnit and should be 
left blank. 

Note: For a character device driver that supports multiple devices, 
the data segment contains a device driver header for each device. 
These headers must be linked together and the first header must be 
set to -1. The first word is an offset and the second word is the 
segment. 

Device Attribute Fieid 

The Device Attribute field describes the characteristics of the device 
driver to the system. 
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The format of the OS/2 device attribute field is: 



15 


14 


13 


12 


11 


10 


9 8 7 


6 


5 


4 


3 


2 


1 


0 


C 


/// 


1 


S 


0 


/// 




/// 


/// 


/// 


C 


N 


S 


K 


H 


/// 


B 


H 


P 


/// 


LEVEL 


/// 


/// 


/// 


L 


U 


c 


B 


R 


/// 


M 


R 


N 


/// 




/// 


/// 


/// 


K 


L 


R 


D 



The attributes are: 
B/(# Meaning 

15 Set if character device driver 
14 Reserved = 0 

13 Set if non-IBM block format, (block device drivers only). Set 
for output-until-busy support, (character device drivers only). 

12 Set if support shared device access checking (character 
devices) 

11 Set if support removable media (block devices) or device 

open/close (character devices) 
10 Reserved = 0 

9-7 Function level where 001 = OS/2 device driver 

6 Reserved = 0 

5 Reserved = 0 

4 Reserved = 0 

3 Set if CLOCK device 

2 Set if NULL device 

1 Set if standard output device (STDOUT) 

0 Set if standard input device (STDIN) 

Bit 15 Bit 15 is the device type bit. Use bit 15 to tell th^ system if the 
device driver is a block or character device. For block device 
drivers, bit 15 is 0. For character device drivers bit 15 is 1. 

Bit 13 For block device drivers, bit 13 indicates the method the driver 
uses to determine the media type. 

If a block device driver uses information in the BPB to deter- 
mine the media type, bit 13 should be set to 1. If the device 
driver uses the media descriptor byte to determine the media 
type, bit 13 should be 0. 
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Bit 12 Bit 12 is the shared bit. It Is set if the device name is NOT to 
be protected by sharer. (Has no meaning for blocl< device 
drivers, must be 0.) 

If clear (default), file system sharing rules DO NOT apply to the 
device, and it is the responsibility of the device driver to 
provide contention control. 

If set, file system sharing rules DO apply to the device, just like 
they apply to any other file system name. In addition, any 
given physical device may have only one logical name. 
(Devices cannot have aliases.) 

Bit 11 For block device drivers, bit 11 is the removable media bit. If 
set, this bit indicates that the device driver handles removable 
media. 

For character device drivers, bit 11 is the open/close bit. If set, 
this bit indicates that the device driver must receive OPEN 
AND CLOSE request packets. 

Bit 9-7 Bits 9-7 indicate the function level where 001 = OS/2 device 
driver. 

Bit 3 Bit 3 Is the clock device bit. It Is used by a character device 
driver to Indicate the system clock device. 

Bit 2 Bit 2 is the NULL attribute bit. It Is used by character devices 
only. Use bit 2 to tell OS/2 If your character device driver is a 
NULL device. Although there Is a NULL device attribute bit, 
you cannot reassign the NULL device. This is an attribute that 
exists for OS/2 so that OS/2 can tell if the NULL device is being 
used. 

Bits 1 and 0 For character devices, bits 1 and 0 are the standard 

input/standard output bits. Use these bits to tell OS/2 if your 
character device driver Is the new standard Input or standard 
output device. 

Offset to Strategy Routine Field 

The offset to the strategy routine field contains the offset from the 
start of the code segment to the strategy entry point. OS/2 uses this 
offset to call the strategy routine. The pointer is a word value con- 
tained In the device header. 
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Name/Units Field 



The name/units field contains tlie name of a cliaracter device sup- 
ported by the character device driver or the number of units sup- 
ported by the blocic device driver. 

For a character device driver, the name of the device must be ASCIi 
characters and must be left-justified with the remaining space set to 
blanl(s. The device name is used by applications to identify the 
device for I/O. A character device driver should consider the fol- 
lowing rule when selecting a device driver name. 

• Rule 

A device name takes precedence over a filename in a DosOpen 
function call. This means that files cannot have the same name 
as a character device. The DosOpen function call will always 
open the device rather than the file. 

Note: To avoid such conflicts with filenames, a character device 
driver should choose a character string with some unusual char- 
acter such as a $ sign. 

For a block device driver, the number of units can be placed in the 
first byte. This Is optional because OS/2 will fill this field during 
device driver initialization. 

For character device drivers using ABiOS, the device name repres- 
ents a single device identified by the Logical ID (LID). For block 
device drivers using ABIOS, the number of units is equivalent to the 
number of devices (or units) under the LID. 
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Creating a Device Driver 



To create a device driver tiiat OS/2 can install, perform the following: 

• Originate the device header at 0, not at 100H. 

• Set up the device header fields. 

• Link the segments as a library. 

Note: Because OS/2 installs the driver anywhere in memory, care 
must be fallen in any memory references. You should not expect that 
your driver will always be loaded at the same place every time. 



Device Driver Initialization 



Device driver initialization occurs during system initialization. During 
system initialization, base device drivers are preloaded with the 
operating system. Installable device drivers are loaded during 
CONFIG.SYS processing, via the DEVICE = configuration command. 
After a device driver has been loaded, it will be called at its strategy 
routine entry point with the request pacl<et for the INIT command. 

OS/2 device drivers have the following characteristics at INIT-time: 

• Occupy memory below 640 Kb. 

• Initialize in the OS/2 mode. 

• Are able to use Advanced BIOS services at INIT-time. 

• Have lOPL at all times. 

• Are able to service hardware interrupts. 

• Are able to use timer services. 

• Are able to use some OS/2 dynamic link function calls. 
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During CONFIG.SYS processing, eacii DEVICE = command is proc- 
essed on a first-come-first-serve basis: 

• The DEVICE = device driver file image is loaded into low 
memory. 

• The checic for DEINSTALL of a previously initialized device driver 
is performed. 

• If DEINSTALL is successful, then the newly loaded device driver 
is initialized. 

Installable OS/2 device drivers initialize in the OS/2 mode. The 
device driver strategy routine will run under the thread of the System 
Initialization Process, at application level, with I/O privilege. 
Because of the special system process, the installable device driver 
is allowed to make dynamic link function calls only at INIT-time. 

Device Driver INIT-Time Function Call Summary 

For function call details, refer to Technical Reference, Vol. 2. 

The list of function calls that the device driver can make is as follows: 

DosBeep Generate Sound From Speaker 

DosCaseMap Perform Case Mapping 

DosChgFllePtr Change (Move) File Read/Write Pointer 

DosClose Close File Handle 

DosDelete Delete File 

DosDevConfIg Get Device Configuration 

DosDevlOCtI I/O Control for Devices 

DosFlndClose Close Find Handle 

DosFindFirst Find First Matching File 

DosFindNext Find Next Matching File 

DosGetCtrylnfo Get Country Information 

DosGetDBCSEv Get DBCS Environmental Vector 

DosGetEnv Get Address of Process Environment String 
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DosGetMessage System Message with Variable Text 

DosOpen Open File 

DosPutMessage Output Message Text to Indicated Handle 

DosQCurDIr Query Current Directory 

DosQCurDisk Query Current Disic 

DosQFilelnfo Query File Information 

DosQFIIeMode Query File Mode 

DosRead Read from File 

DosWrite Synchronous Write to File 

DevHIp services are also available to device drivers at INIT-time. 

Note: Because device driver initialization is invoked by way of the 
strategy routine, the device driver must not issue a DosExit function 
call. Instead, the device driver should return the INIT request packet 
by setting the packet's return status and performing a FAR RET to the 
kernel. 

For more information see "OH / INIT Initialize Device" on page 7-43. 

Replacing Character Device Drivers 

OS/2 character device drivers can be replaced. For system char- 
acter device drivers, the appropriate bits in the attribute field of the 
device driver header and the name of the character device driver 
must match. 

When the new device driver is loaded, the attribute field and name 
are used to determine if the new device driver is attempting to 
replace a driver already installed. If so, the previously installed 
device driver is requested to DEINSTALL the indicated device. If the 
already-installed device driver refuses the DEINSTALL command, the 
new device driver is not allowed to initialize. If the already-installed 
device driver performs the DEINSTALL, the new device driver is ini- 
tialized. 

Note: The DEINSTALL command is needed to allow a device driver to 
relinquish its interrupt vectors and its allocated physical memory. 
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Compatibility witti Previous-Level Device Drivers 

The term "previous-level" Is used here to Indicate DOS levels below 
DOS 3.3 

Not all previous-level DOS device drivers can be allowed to run In the 
DOS mode. The supported set of previous-level device drivers has 
the following restrictions: 

• Previous-level block device drivers are not permitted In the DOS 
mode. Block device drivers must be written to the OS/2 Inter- 
faces. 

• Only a limited set of previous-level character device drivers can 
be supported by OS/2. In order to run in the DOS mode, a 
previous-level character device driver must conform to the fol- 
lowing rules: 

— The character device driver cannot have a hardware interrupt 
handler; its device must be a polled device rather than an 
Interrupt-driven one. 

- The character device driver can be called by OS/2 in the 
DOS mode with all of the packets supported by character 
devices: 

0 - INIT 

3-IOCtl input 

4 - INPUT (read) 

5 - NON-DESTRUCTIVE INPUT NO WAIT 

6 - INPUT STATUS 

7 - INPUT FLUSH 
8 -OUTPUT 

9 — OUTPUT with verify 
10 -OUTPUT STATUS 

11 - OUTPUT FLUSH 

12 — lOCtI output 

13 - DEVICE OPEN 

14 - DEVICE CLOSE 
16 -GENERIC lOCtI 

Receipt of these packets is limited by the same require- 
ments on the attribute field of the device header as in DOS 
3.3. For example: lOCtI bit In the device header must be 1 to 
receive lOCtI requests. 
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The side effect of running a previous-level character device driver is 
that its device may be used only in the DOS mode. Only applications 
running in the DOS mode can perform I/O to this device. Applications 
in the OS/2 mode are not allowed to access the device. 

Certain devices cannot be exclusive to the DOS mode. Character 
devices in this category include: 

• Mouse 

• Clock 

Consequently, a previous-level clock device driver cannot be sup- 
ported. 

Initialization of Previous-Level Device Drivers 

Previous-level character device drivers are installed in the same 
manner as they were under DOS. The device driver program file is 
specified in the configuration command, DEVICE = . 

Previous-level device drivers are loaded and initialized In DOS mode. 
The rules for replacing previous-level character device drivers are 
the same. The replacement is guided by the name and attributes of 
the device driver. The functions that can be performed at initializa- 
tion are more restrictive than for DOS 3.3. No INT 21 H functions can 
be performed from the device driver initialization code. 

DOS Execution Environment Generic lOCtI Support 

There are two types of generic lOCtIs supported in the DOS mode. 

• Function: AL=ODH 

Wh^re this function is the same as DOS 3.3 with the addition that 
the register pair SI:Di is the address of the parameter block in 
OS/2 and DS:DX is the address of the data packet. 

• Function: AL = OCH 

This function is similar to function AL=ODH except that BX con- 
tains a handle to a device instead of a drive letter. This function 
is useful for character devices. 
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The register contents are as follows: 

Register Contents 

AH 44H - lOCtI request 
AL ODH — Drive oriented 

OCH — Handle oriented 
BL Drive number 
BX Handle value 
CH Category 
CL Function 
DS-.DX Data block 
SI:DI Parameter block 



Refer to the specific device lOCti descriptions for the Categories and 
Functions supported. 

DOS Execution Environment Software interrupt Support 

The following is a list of the software interrupts supported and the 
compatibility exceptions for DOS mode operation: 



Interrupt 

05H Print screen 



12H Memory size 



13H Disk / Diskette 



Commente 

Request ignored 

Note: Shift-Print screen works for text 
mode screens in both the OS/2 and DOS 
modes. 



Supported 
size 



size limited to DOS mode 



For non-removable media only — these 
functions are supported: 

01 H — read status 
02H — read sectors 
OAH — read long 
15H — read DASD type 
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14H ASYNC 



15H Misc 



17H Printer 

19H Reboot (Re-start) 



1AH TOD 



If the ASYNC device driver is loaded in 
the system, then INT 14H will not function 
for its related ASYNC ports unless the 
utility SETCOM40 is used. See 
SETCOM40 in the User's Reference for 
INT 14H considerations. 

Functions not supported: 

87H - Block Move 

88H — Extended memory size 

89H — Virtual mode 

90H — Device busy 

91 H — Int. complete 

Functions supported with restrictions: 

83H — Event wait 
86H - Wait 

Note: Both 83H and 86H are supported; 
but the timer granularity is on the order 
of 31ms. Because the RTC (Real Time 
Clock) is free running, there will be a var- 
iance of up to 1 RTC tick. 

Supported by OS/2 device driver 

Supported — However, this does not 
operate in the same manner as DOS 3.3. 
The system is restarted as if Ctrl-Alt-Del 
was pressed. 

Functions not supported: 

02H — Read RTC time 
03H — Set RTC time 
04H — Read RTC date 
05H - Set RTC date 
06H — Set RTC alarm 
07H — Reset RTC alarm 
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1EH Diskette parameters Not used by device driver after boot 

process 

24H Hard error Supported — OS/2 calls the application 

wlien a hard error occurs. 

26H Direct write An error is returned on requests for non- 

removable media. 

2FH Multiplex Returns error "Not installed, not to be 

installed" (printer only — request AL=0 
returns AL = 1); 

33H Mouse Supported — When the OS/2 Mouse 

device driver is loaded, INT 33H functions 
are available. 

Using Advanced BIOS 

There are two methods that device drivers may use to invoke 
Advanced BIOS, the Advanced BIOS Transfer Convention and the 
Operating System Transfer Convention. For the Advanced BIOS 
Transfer Convention, the Advanced BIOS Common Entry Points are 
Invoked to locate the specific Start, Interrupt, or Timeout entry points 
for the requesting Logical ID. For the Operating System Transfer 
Convention, the specific Start, Interrupt, or Timeout entry points must 
be located for the requesting Logical ID and called. 

OS/2 internal device drivers use the Operating System Transfer Con- 
vention to invoke Advanced BIOS services. User-written, installable, 
device drivers may use either the Advanced BIOS Transfer Conven- 
tion or the Operating System Transfer Convention. DevHIps are pro- 
vided for both calling conventions. 

Note: Both kinds of device drivers mentioned above will be com- 
monly termed as ABIOS device drivers. 



7-33 



For performance reasons, ABIOS device drivers siiould call 
Advanced BIOS services witli processor interrupts enabled. 

Device Driver Data Segment 

OS/2 recommends that an ABIOS device driver use its data segment 
to contain the Advanced BIOS request bloclts and data transfer 
buffers. The device driver data segment is located in low memory 
and the operating system guarantees addressability to the data 
segment regardless of the processor mode (protect or real). The 
device driver may also assume that the physical location of the 
device driver data segment will not move. This will allow physical 
data transfers to take place to buffers within the device driver's data 
segment. 

By using its data segment, the device driver can create logical 
addressability to these data areas (for Advanced BIOS) in a mode- 
independent manner and without interrupt disable time consider- 
ations. Physical data transfers to buffers outside of the device 
driver's data segment may take place if the buffer is locked. 

Obtaining a Logicai ID 

During its initialization, an ABIOS device driver must obtain the 
Logical ID (LID) for its physical device. 

The allocation of a LID is managed by the operating system. This 
ensures that the device driver gets a unique LID for its device type. 
The operating system provides a DevHIp function GetLIDEntry to 
obtain the LID for a device driver. 

The DevHIp GetLIDEntry finds the LID for the specified Device ID and 
allocates it to the calling device driver. 

The counterpart to GetLIDEntry is the DevHIp FreeLIDEntry. This 
service is required when the device driver DEINSTALLS or terminates 
to release the device driver's claim to the LID. Refer to the section 
"DEINSTALL Considerations" on page 7-64 for more details. 
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The operating system will prohibit access to a certain LID; specif- 
ically, the LID for System Services. The operating system manage- 
ment of LID access is similar to the management of hardware 
interrupt levels or I/O ports. 

Calling Advanced BIOS Services 

For ABIOS device drivers that use the Operating System Transfer 
Convention, a DevHIp service (ABIOSCall) is provided to involve 
Advanced BIOS with the mode specific correct set of parameters. 
The device driver passes the ABIOS request block pointer, its LID, 
ahd the ABIOS primary function (start, interrupt, or timeout) to the 
DevHIp ABIOSCall. This sets up the stack for the call to Advanced 
BIOS and calls the ABIOS function. 

For ABIOS device drivers that use the Advanced BIOS Transfer Con- 
vention, a DevHIp service (ABIOSCommonEntry) is provided to invoke 
the Advanced BIOS Common Entry Points The device driver passes 
the mode specific pointer to the ABIOS request block and the ABIOS 
primary function (common start, common interrupt, or common 
timeout) to the DevHIp service. The DevHIp service sets up the stack, 
and calls the requested ABIOS common entry point. 

Note: The return code of the ABIOS function will be in the ABIOS 
request block. 

Mapping Device Names to LID 

Having identified its LID and the number of devices or physical units 
the LID represents, the device driver must map each of its device 
names to a unit within that LID. 

Note: A device driver supports all units under a given LiD. 

All device drivers are known to the operating system by device 
names, whether these names correspond to the ASCII string device 
name in the header for character device drivers or to the logical units 
(which correspond to drive letters) in the header for block device 
drivers. 
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In the case of a character device driver with a single device driver 
header, Its device name must be mapped to the first unit of the LID it 
obtained. If the character device driver has one device header but its 
LID had multiple units, then the rest of the units are not used. 

In the case of a character device driver with multiple device driver 
headers, the operating system will call the strategy routine entry 
point for each header during device driver initialization. 

1 . The first entry point called must map its device name to the first 
unit of the LID. 

2. The second entry point called must map its device name to the 
next unit of the LID. 

3. If the LID that was obtained by the first entry point has only one 
unit, the second entry point must obtain another LID and map its 
device name to the first unit of the second LID. 

4. The device driver must start with the first LID and consume all the 
units before going to the next LID. 

For example: 

The printer device driver has three device headers (LPT1, LPT2, and 
LPT3), respectively. The first entry point will map LPT1 to the first 
unit of the LID it obtained (let's use LID #12). If LID #12 supports only 
one unit, the second entry point will map LPT2 to the first unit of 
another LID it must obtain (let's use LID #17). If LID #17 supports 
another unit, the third entry point will map LPT3 to the second unit of 
LID #17. 

In the case of a block device driver, the block device driver must 
obtain the necessary number of LID/units for the number of logical 
units it supports. The block device driver maps the first logical unit to 
the first-LID/first-unit, the second logical unit to the next available 
LID/unit, and so forth. 

Handling ABIOS Requests 

Refer to "Notes On Writing a Device Driver using Advanced BIOS" on 
page 7-72, for a discussion on handling requests to Advanced BIOS. 

A device driver must assume that it owns all outstanding ABIOS 
request blocks for a given Logical ID. During interrupt-time proc- 
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essing, the device driver must call Advanced BIOS for eacli out- 
standing request that is Incomplete-Waiting-On-lnterrupt. 

Note: This in one of the reasons that a Logical ID Is not shared 
among device drivers. 



Request Packets 

The device driver strategy routine is called with ES:BX pointing to the 
request packet. The pointer to the request packet (ES:BX) Is bimodal. 
In other words, the pointer is valid In both the DOS mode and the 
OS/2 mode. 

OS/2 does not guarantee that the order of API requests that are 
Issued by multiple threads will be preserved in the ordering that the 
corresponding request packets arrive at the device driver. Multiple 
application threads or threads created due to DosReadAsync and 
DosWriteAsync can get blocked in the operating system. This allows 
a device driver request packet for an API request by a subsequent 
thread that does not get blocked to arrive out of order. A device 
driver is responsible for providing a synchronization mechanism 
between itself and application processes if it supports multiple out- 
standing requests; also, request packet ordering must be preserved. 
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The request packet consists of two parts, the request header and the 
command-specific data field. The format of the request packet is 
detailed below. 



Field 


Length 


Length of Request Packet 


BYTE 


Block Device Unit Code 


BYTE 


Command Code 


BYTE 


Status 


WORD 


Reserved 


DWORD 


Queue Linkage 


DWORD 


Command-specific Data 


BYTES 



Length of Request Packet Field 

The length of the request packet is set to the total length In bytes of 
the request packet (the length of the request header plus the length of 
the data). 

Bloek Device Unit Code Field 

The bidck device unit code identifies the unit for which the request is 
intended. This field has no meanirig for character devices. 

Command Code Field 

The command code Indicates the requested function. The command 
codes are listed In the following summary. 
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Summary of Commands for Devices 



CODE 


FUNCTION 


BLOCK 


CHAR 


OH 


INIT 






1H 


MEDIA CHECK 






2H 


BUILD BPS 






3H 


Reserved 






4H 


READ (input) 






5H 


NONDESTRUCTIVE READ NO WAIT 






6H 


INPUT STATUS 






7H 


INPUT FLUSH 






8H 


WRITE (output) 






9H 


WRITE WITH VERIFY 






AH 


OUTPUT STATUS 






BH 


OUTPUT FLUSH 






CH 


Reserved 






DH 


DEVICE OPEN 






EH 


DEVICE CLOSE 






FH 


REMOVABLE MEDIA 






10H 


GENERIC lOCtI 






11H 


RESET MEDIA 






12H 


GET LOGICAL DRIVE MAP 






13H 


SET LOGICAL DRIVE MAP 






14H 


DEINSTALL 






15H 


Reserved 






16H 


PARTITIONABLE FIXED DISKS 






17H 


GET FIXED DISK/LOGICAL UNIT MAP 


* 




18H 


Reserved 






19H 


Reserved 






1AH 


Reserved 







The commands are described in detail in tlie command section of this 
chapter. 
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Request Packet Status Field 

On entry to the strategy routine, the status field is only defined for 
Open and Close request packets. For all other request packets the 
status field is undefined on entry. 

I 

For an Open request packet, Bit 3 (08H) of the status field is SET if the 
packet was generated from a DosMonOpen, otherwise it was a 
DosOpen. 

For a Close request packet, Bit 3 (08H) of the status field is SET if the 
packet was generated by a DosMonClose or a DosClose of a handle 
that was generated by a DosMonOpen (so that monitor handles gen- 
erated that are left open when a process exits will be closed prop- 
erly). Otherwise, It was a DosClose on a non-monitor handle. 

On exit from the strategy routine the status field describes the 
resulting state of the request as shown below: 



15 


14 


13-10 


9 


8 


7-0 


E 


D 


RESERVED 


B 


D 


ERROR CODE 


R 


E 




U 


0 


(bit 15 on) 


R 


V 




S 


N 




0 






Y 


E 




R 


E 












R 












R 












0 












R 











Bit 15 is the Error bit. If this bit is set, the low 8 bits of the status word 
(7-0) indicate the error code. 

Note: If the category is user-defined, then the error returned to the 
caller is FFOOh ANDed with the byte-wide error code. 

Bit 14 is a device driver defined error if set in conjunction with bit 15. 

Note: If the category is user-defined, then the error returned to the 
caller is FEOOh ANDed with the byte-wide error code. 

Bits 13 - 10 are reserved. 
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Bit 9 is the Busy bit. It is only set by status calls and the removable 
media call. See "STATUS" and "REMOVABLE MEDIA" in this 
chapter for more information about the calls. 

Bit 8 is the Done bit. If it is set, it means the operation is complete. 
The driver sets the done bit to 1 when it exits. 

Bits 7-0 are the low 8 bits of the status word. If bit 15 is set, bits 7-0 
contain the error code. The error codes and errors are: 

Error Codes Description 



OOH Write protect violation 

01H Unknown unit 

02H Device not ready 

03H Unknown command 

04H CRC error 

05H Bad drive request structure length 

06H Seek error 

07H Unknown media 

08H Sector not found 

09H Printer out of paper 

OAH Write fault 

OBH Read fault 

OCH General failure 

ODH Change disk (logical switch) 

OEH Reserved 

OFH Reserved 

10H Uncertain media 

11 H Character I/O call interrupted 

12H Monitors not supported 

13H Invalid parameter 



Uncertain Media (10H) should be returned when the state of the 
media In the drive is uncertain. This response should NOT be 
returned to the INIT command. For fixed disks, the device driver must 
begin in a Media Uncertain state in order to have the media correctly 
labelled. In general, the following guidelines may be used to deter- 
mine when to respond with uncertain media. 

• When a drive-not-ready condition is detected. (In this case, 
return uncertain media to all subsequent commands until a reset 
media command is received. 
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• When accessing removable media without change-line support, 
and a time delay of two or more seconds has occurred. 

• When the state of the change-line Indicates that the media may 
have changed. 

Character I/O call interrupted (11 H) should be returned when the 
thread performing the I/O was interrupted out of a DevHIp Block 
before completing the requested operation. 

Monitors not supported (12H) should be returned for monitor com- 
mands (monitor open/close, register lOCtI) if monitors are not sup- 
ported by the device driver. 

Invalid parameter (13H) should be returned when one or more fields 
of the request packet contain invalid values. 

Queue Linkage Field 

The queue linkage is provided to maintain a linked list of request 
packets. The device driver may use the request queue management 
DevHIp services, or it may use its own queue management. 

Note: Because a pointer to a request packet is bimodal (valid in both 
the DOS mode and the OS/2 mode), the pointer may be used directly 
in the queue linkage rather than a 32-bit physical address. 

Command-Specific Data Field 

The command code in the request header tells the device driver 
which function to perform. 

The function and parameters of a command appear in the command- 
specific data area of the request packet. The commands and the 
actual formats of the corresponding request packets are discussed in 
the following sections. 

Note: All DWORD pointers are stored with offset first, then segment. 
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OH / INIT 
initialize Device 



Purpose 

Initialize the device. 

Format of Request Block 



Field 


Length 


Request header 


13 BYTES 


Data_1 


BYTE 


PointeM 


DWORD 


Polnter_2 


DWORD 


Data_2 


BYTE 



Remarks 

On entry, the request block contains the following fields as inputs to 
the device driver: 

Pointer_1 Points to the DevHIp Entry Point 

Pointer_2 Points to the INIT arguments 

Data_2 Drive number for the first block device unit 

The DevHIp Entry Point Is a bimodal address and is valid in both the 
DOS mode and the OS/2 mode. 

The DevHIp Entry Point is called to invoke a service specified in the 
DL register. 

The arguments for installable device drivers from the DEVICE = line 
in the CONFIG.SYS file allow the device driver to use configurable 
parameters to initialize itself and its device. 
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OH / INIT 
Initialize Device 



At initialization time, the device driver runs as a tliread under a 
protect mode process at application level with I/O privilege. The 
device driver may issue certain OS/2 dynalink function calls at this 
time. Refer to "Device Driver Initialization" on page 7-26 for more 
details. 



On completion of initialization, the device driver must set fields in the 
request pacl<et as described: 

Field OUTPUT Information for INIT success 

Data_1 Number of logical block devices or units (block devices 
only) 

Pointer_1 WORD offset to end of code segment 

WORD offset to end of data segment 

Pointer_2 Points to the BPB array for the logical block devices or 
units (block devices only) 

Status Set the status word in the request header to 0100H 



A block device driver must return in Data_1 the number of logical 
devices or units that are available. The kernel's file system layer will 
assign sequential drive letters to these units. A character device 
driver will set Data_1 to zero. 

Both block device drivers and character device drivers must set 
Pointer_1 with the offsets of the code and data segments. This allows 
a device driver to release code and data needed only by the device 
driver's initialization routine. First, the initialization code and data 
must be located at the end of the appropriate segments. Then, as the 
final step in initialization, the device driver sets the offsets to the end 
of the code segment and the end of the data segment. This also 
permits a device driver to load with a maximum-sized data segment 
(64 Kb) and let it release the amount that it does not need. 

Note: Remember that the device driver code and data segments 
reside in memory below 640K. The DOS mode requires contiguous 
memory below 640K. Although memory returned by the device driver 
from its data segment is available to the system, It is not available for 
the DOS mode. 
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OH / INIT 
Initialize Device 

A block device driver must return an array of BPBs for the logical 
units that it supports in Pointer_2. A character device driver will set 
Pointer_2 to zero. 

The Status field in the request packet header must be set to indicate 
no error and done. 

If the device driver determines that it cannot set up the device and 
wants to quit, it is recommended that it return with the error bit in the 
request packet status field set to 1. The device driver can also return 
the following: 

Field OUTPUT Information for INIT failure 

Data_1 BYTE OOH 
PointerJ WORD OOOOH 
WORD OOOOH 
Status 81 OOH 

The status field in the request packet header must be set to indicate 
the failure of the INIT request with the General Failure error return 
code. The Status must also indicate that the request is done. 

One of the above techniques must be used to return device initializa- 
tion failures from the device driver to the system initialization 
process. 

A character device driver that contains multiple device driver 
headers can fail initialization on a subset of the headers in its header 
chain. 

The system initialization process remembers the last non-zero size 
code and data segment offsets returned for the devices in the device 
driver that completed initialization. These last values are used to 
resize the device driver's code and data segments after INIT packets 
have been sent to the device driver for each device in the device 
driver header chain. 
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OH / INIT 
Initialize Device 



When a device in tlie header chain cannot be initialized, the device 
driver can set the code and data segments to zero, and/or set the 
error bit in the request packet status field to indicate initialization 
failure for that device. The device driver will not receive any future 
request packets for a specific device if it returns a failure for the INIT 
request packet for that device- If none of the devices in the device 
driver header chain pass initialization, then the device driver will not 
remain loaded. 

Because the system Initialization process maintains the pass/fall 
return status for each device header in a device driver header chain, 
it Is not recommended that the device driver manipulates the linkages 
of the headers. 
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1H/ MEDIA CHECK 
Check the Media 



Purpose 

Determine the state of the media. 



Format of Request Block 



Field 


Length 


Request header 


13 BYTES 


Media descriptor 


BYTE 


Return code 


BYTE 


Return pointer to previous voiume ID if 
supported 


DWORD 



Remarks 

On entry, the request packet will have the media descriptor field set 
for the drive identified in the request packet header. 

The device driver must perform the following actions for the MEDIA 
CHECK request: 

• Set the status word in the request packet header. 

• Set the return code where: 

-1 = Media has been changed 

0 = Unsure if media has been changed 

1 = Media unchanged 
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1H/ MEDIA CHECK 
Check the Media 



Examples of DOS media descriptor bytes: 



Disk TvDS 


# 

Sides 


# 

Sectors/ 
Track 


Media 
DascrlDtor 


Fixed disl< 






F8H 


3 1/2-incli 

W % w mm II IWI i 


2 


9 


F9IH 


3 1/2-inch 

W l/b IllWil 


2 


18 


FOH 


5 1/4-inch 

W 1 f lllwll 


2 


15 


F9l-i 


5 1/4-inch 

W If ~ 1 1 1 Wl 1 


1 


9 


FCH 


5 1/4-inch 


2 


9 


FDH 


5 1/4-inch 


1 


8 


FEH 


5 1/4-inch 


2 


8 


FFH 


8-inch 


1 


26 


FEH 


8-inch 


2 


26 


FDH 


8-inch 


2 


8 


FEH 



Note: To determine whether you are using a single-sided or a 
double-sided diskette, for 8-inch diskettes (FEH), attempt to read the 
second side, and if an error occurs you can assume the diskette is 
single-sided. 

For 8-inch diskettes: 

FEH (IBM 3740 Format). Single-sided, single density, 128 bytes 
per sector, soft sectored, 4 sectors per allocation unit, 1 reserved 
sector, 2 File Allocation Tables (FATs), 68 directory entries, 77*26 
sectors. 

FDH (IBM 3740 Format). Double-sided, single density, 128 bytes 
per sector, soft sectored, 4 sectors per allocation unit, 4 reserved 
sectors, 2 FATs, 68 directory entries, 77*26*2 sectors. 
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1H/ MEDIA CHECK 
Check the Media 



FEH Double-sided, double density, 1024 bytes per sector, soft 
sectored, 1 sector per allocation unit, 1 reserved sector, 2 FATs, 
192 directory entries, 77*8*2 sectors. 

Application programmers are encouraged to use the Generic lOCtI — 
Get Device Parameters (Category 8, function 63) and reference the 
BPB (BIOS Parameter Block) to determine the type of media. 
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2H / BUILD BPB 

Build BIOS Parameter Block 



Purpose 

Build the BIOS Parameter Block (BPB). This is requested when the 
media has changed or when the media type is uncertain. 



Format of Request Block 



Field 


Length 


Request header 


13 BYTES 


Media descriptor 


BYTE 


Transfer address 


DWORD 


Pointer to BPB table 


DWORD 


Drive number 


BYTE 



Remarks 

On entry, the request packet will have the media descriptor set for the 
drive identified in the request packet header. The transfer address is 
a virtual address to a buffer containing the boot sector media if the 
block device driver attribute field has bit 13 set, otherwise the buffer 
contains the first sector of the File Allocation Table (FAT). 

The device driver must perform the following actions: 

• Set the pointer to the BPB table. 

• Update the media descriptor. 

• Set the status word in the request header. 

The device driver must determine the media type in the drive in order 
to return the pointer to the BPB table. Previously, the FAT ID byte 
determined the structure and layout of the media. Because the FAT 
ID byte has only eight possible values (F8 through FF), it is clear that, 
as new media types are invented, the available values will soon be 
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2H / BUILD BPB 
Build BIOS Parameter Block 



exhausted. With the varying media layouts, OS/2 needs to be aware 
of the location of the FATs and directories before it reads them. 

The device driver reads the boot sector from the specified buffer. If 
the boot sector is for DOS 2.00, 2.10, 3.10, 3.20, or OS/2, the device 
driver returns the BPB from the boot sector. If the boot sector is for 
DOS 1.00 or 1.10, the device driver reads the first sector of the FAT 
into the specified buffer. The FAT ID is examined and the corre- 
sponding BPB is returned. Only two formats are possible for 
diskettes formatted by a 1.00 or 1.10 system, 5 1/4-inch single-sided 
(FEH) and 5 1/4-inch double-sided (FFH.) 

The information relating to the BPB for a particular media Is kept In 
the boot sector for the media. 

Boot Sector Format 



Field 


Length 


Short JUMP (EBH) followed by a NOP 
(90H) 


2 BYTES 


OEM name and version 


8 BYTES 


Bytes per sector 


WORD 


Sectors per allocation unit (must be a 
power of 2) 


BYTE 


Reserved sectors (starting at logical 
sector 0) 


WORD 


Number of FATs 


BYTE 


Number of root directory entries 
(maximum allowed) 


WORD 


Number of sectors in logical image (total 
sectors in media, including boot sector, 
directories, for example.) 


WORD 
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2H / BUILD BPB 

Build BIOS Parameter Block 



Field 


Length 


Media descriptor 


BYTE 


Number of sectors occupied by a single 
FAT 


WORD 


Sectors per track 


WORD 


Number of heads 


WORD 


Number of hidden sectors 


WORD 



The last three WORDs above help the device driver understand the 
media. The number of heads is useful for supporting different mul- 
tiple head drives that have the same storage capacity but a different 
number of surfaces. The number of hidden sectors is useful for sup- 
porting drive partitioning schemes. 

For drivers that support volume identification and dlsl^ change, this 
call should cause a new volume identification to be read off the disk. 
This call indicates that the disk has legally changed. 
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4H, 8H, 9H / READ or WRITE 
Perform I/O To A Device 



Purpose 

Read from or write to a device. 

Read From (4H) / Write To (8H) / Write with Verity (9H) 



Format of Request Block 



Field 


Length 


Request header 


13 BYTES 


Media descriptor 


BYTE 


Transfer address 


DWORD 


Byte / sector count 


WORD 


Starting sector number for blocl< device 


DWORD 


System File Number 


WORD 



Remarks 

On entry, the request packet will have the media descriptor set for the 
drive identified in the request packet header. The transfer address is 
a 32-bit physical address of the buffer for the data. The byte/sector 
count is set to the number of bytes to transfer (for character device 
drivers) or the number of sectors to transfer (for block device 
drivers). The starting sector number is set for the block device 
drivers. The System File Number Is a unique number associated with 
an open request. 

The device driver must perform the following actions: 

• Perform the requested function. 

• Set the actual number of sectors or bytes transferred. 

• Set the status word in the request header. 
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4H, 8H, 9H / READ or WRITE 
Perform I/O To A Device 



The DWORD transfer address in the request packet is a locked 32-bit 
physical address. The device driver can pass it to the DevHIp func- 
tion PhysToVirt to obtain a segment swapping address for the current 
mode. The device driver does not need to unlock the address when 
the request is completed. 

Note: The functions lOCtI READ and lOCtI WRITE are not supported 
by the new OS/2 device drivers. 
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5H / NONDESTRUCTIVE READ NO WAIT 

Nondestructive Input 



Purpose 

Read character from buffer but do not remove it. 
Format of Request Block 



Field 


Length 


Request header 


13 BYTES 


Returned character 


BYTE 



Remarks 

The device driver must perform the following actions: 

• Return a byte from the device. 

• Set the status word in the request header. 

For input on character devices with a buffer, the device driver returns 
from this function with the busy bit set to 0 along with a copy of the 
first character in the buffer. The busy bit is set to 1 to Indicate no 
characters in the buffer. This function allows the operating system to 
look ahead one input character without blocking in the device driver. 
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6H, AH / STATUS 
Input or Output Status 



Purpose 

Determine input or output status on character devices. 
Input Status (6H) / Output Status (AH) 



Format of Request Block 



Field 


Length 


Request header 


13 BYTES 



Remarks 

The device driver must perform the following actions: 

• Perform the requested function. 

• Set the busy bit. 

• Set the status word in the request header. 

For output on character devices, if the busy bit is returned set to 1, a 
subsequent write request to the device driver would have to wait for 
the completion of a currently active request. If the busy bit is 
returned set to 0, there is no current request. Therefore, a write 
request would start immediately. 

For input on character devices with a buffer, if the busy bit is returned 
set to 1, there are no characters currently buffered in the device 
driver. If the busy bit Is returned set to 0, there is at least one char- 
acter in the device driver buffer. The effect of busy bit = 0 Is that a 
read of one character will not need blocking. Devices that do not 
have an input buffer in the device driver should always return busy = 
0. 



7-56 



7H, BH / FLUSH 
Input or Output Flush 



Purpose 

Flush or terminate ail pending requests. 
Input Flush (7H) / OutPut Flush (BH) 

Format of Request Block 



Field 


Length 


Request header 


13 BYTES 



Remarks 

The device driver must perform the following actions: 

• Perform the requested function. 

• Set the status word in the request header. 

This call tells the device driver to flush (terminate) all known pending 
requests. Its primary use is to flush the input (or output) queue on 
character devices. 
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DH, EH / OPEN or CLOSE 
Open / Close Device 


Purpose 




Open or close the device. 

Open Device (DH) / Close Device (EH) 




Format of Request Block 




Field 


Length 


Request header 


13 BYTES 


System File Number 


WORD 



Remarks 

The System File Number Is a unique number associated with an open 
request. 

The device driver must perform the following actions: 

• Perform the requested function. 

• Set the status word in the request header. 

Character device drivers may use OPEN/CLOSE requests to correlate 
using their devices with application activity. For instance, the device 
driver may Increase a reference count for every OPEN and decrease 
the reference count for every CLOSE. When the count goes to 0, the 
device driver can flush its buffers. This can be thought of as a "last 
close causes flush," or as the device driver using the OPEN as an 
indicator to send an initialization string to its device. 

For example, to ensure that a printer is in a known state at the start of 
an I/O stream, this call could be used to set the font and page size. 
Similarly, the CLOSE call can be used to send a post-string {Wke a 
form feed) at the end of an I/O stream. Using lOCtI to set these pre- 
strings and post-strings provides a flexible mechanism of serial I/O 
device stream control. 
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FH / ftlMOVABLE MEDIA 
Cbeck for Remoyable Media 



Purpose 

Check for removable media. 
Format of Request Block 



Field 


Length 


Request header 


13 BYTES 



Remarks 

The device driver miist perform the following actlonis: 

• Set the busy bit of the status word. 

Set the busy bit to 1 if the media is non-removable. Set the busy 
bit to 0 if the media is removable. 

• Set the status word in the request header. 

The device driver receives this request pacl<et when an application 
issues an lOCtI function call to determine whether it is dealing with a 
removable or non-removable media drive. For example, removable 
or non-removable drives may print different versions of some 
prompts. 
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10H / GENERIC lOCtI 
I/O Control for Devices 



Purpose 

Send I/O control commands to a device. 



Format of Request Block 



Field 


Length 


Request header 


13 BYTES 


Function category 


BYTE 


Function code 


BYTE 


Parameter Buffer Address 


DWORD 


Data Buffer Address 


DWORD 


System File Number 


WORD 



Remarks 

On entry, the request packet will have the lOCtI category code and 
function code set. The parameter buffer and the data buffer 
addresses will be set as virtual addresses. Note that some lOCti 
functions do not require data and/or parameters to be passed. For 
these lOCtIs, the parameter and data buffer addresses may contain 
zeros. The System File Number is a unique number associated with 
an open request. 

The device driver must perform the following actions: 

• Perform the requested function. 

• Set the status word in the request header. 

The device driver is responsible for locking the parameter and data 
buffer segments, and converting the pointers to 32-bit physical 
addresses if necessary. 

Refer to Technical Reference, Vol. 2 for more detailed information. 
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11H/ RESET MEDIA 
Reset Uncertain Media Condition 



Purpose 

Reset the Uncertain Media error condition and allow OS/2 to identify 
tlie media. 

Format of Request Block 



Field 


Length 


Request lieader 


13 BYTES 



Remarks 

On entry, the unit code identifies the drive number to be reset. 

The device driver must perform the following actions. 

• Set the status word in the request header. 

• Reset the error condition for the drive. 

Previous to this command, the device driver had returned the error 
"Uncertain Media" for the drive. This action informs the device driver 
that it no longer needs to return the error for the drive. 
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12H, 13H / LOGICAL DRIVE 
Get/Set Logical Drive lUiapping 



Purpose 

Get/Set which logical drive Is currently mapped onto a particular unit. 
Get Logical Drive Mapping (12H) / Set Logical Drive Mapping (13H) 



Format off Request Block 



Field 


Length 


Request header 


13 BYTES 



Remarks 

On entry, the unit code contains the unit number of the drive for which 
this operation is to be performed. 

The device driver must perform the following actions: 

• For Get, it must return the logical drive that is mapped onto the 
physical drive indicated by the unit number in the request header. 

• For Set, it must map the logical drive represented by the unit 
huniber onto the physical drive that has the mapping of logical 
drives. 

• The logical drive is returned in the unit code field. This field is 
set to 0 if there is only one logical drive mapped onto the physical 
drive. 

• Set the status word in the request header. 
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14H / DEINSTALL 
Terminate the Device Driver 



Purpose 

Terminate the character device driver. 



Format of Request Block 



Field 


Length 


Request l-feader 


13 BYTES 



Remarics 

When a device driver is loaded, the attribute field and name in its 
header are used to determine If the new device driver is attempting to 
replace a driver (device) already Installed. If so, the previously 
installed device driver Is requested by the operating system to 
DEINSTALL the indicated device. If the installed device driver 
refuses the DEINSTALL command, then the new device driver is not 
allowed to initialize. If the installed device driver performs the 
DEINSTALL, then the new device driver Is initialized. 

If the character device driver honors the DEINSTALL request, it must 
perform the following actions: 

• Release any allocated physical memory. 

• UnSet any hardware vectors that it had claimed. 

• If the device driver has a software interrupt handler, it cannot 
reset the vector, rather it must preserve the DOS mode vector 
chain by doing a JMP to the previous handler. 

• Perform any other cleanup. 

• Clear the error bit in the status field to indicate a successful 
DEINSTALL. 
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14H / DEINSTALL 
Terminate the Device Driver 



If the character device driver determines that it cannot or wili not 
abort, it should: 

• Set the error bit in the status field and set the error code to 03H, 
UNKNOWN COMMAND. 

DEINSTALL Considerations 

Logicai iDs: An ABIOS device driver maps its device name to a unit 
within a Logical ID (LID). It receives a DEINSTALL request for its 
device name, which implies a single unit of a LID. To honor the 
DEINSTALL request, it must relinquish the LID via the DevHIp 
FreeLIDEntry at DEINSTALL time. 

Note: To release a LID means to release all units under that LID. For 
a LID that has multiple units, the device driver must discontinue 
support of all units under the LID. If multiple units correspond with 
multiple device headers in the device driver data segment, the device 
driver must note which device header corresponds to each unit in the 
DEINSTALL LID, and discontinue support. 

Hardware interrupts: In honoring a DEINSTALL command, a device 
driver must remove its claim on the interrupt level. The DevHIp 
UnSetlRQ provides this service. 

If the device driver's device is ill-behaved (that is, it cannot be told to 
stop generating interrupts or be quiesced), the device driver must not 
remove its interrupt handler. In this case, the device driver must 
refuse the DEINSTALL request. 

Note: Because of the general Interrupt sharing capabilities in a level- 
sensitive interrupt environment, device drivers should not assume 
that the DevHIp SetlRQ service can be used to determine whether a 
given device is being used by another device driver. Instead, the 
DEINSTALL convention should be used on the logical device name 
that another device driver may be using to access the same device. 
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16H / PARTITION ABLE FIXED DISKS 
General query of device support 



Purpose 

This call is used by the system to ask the device driver how many 
physical-partltlonable fixed disks the device driver supports. 

Format of Request Block 



Field 


Length 


Request Header 


13 BYTES 


Count 


BYTE 


Reserved 


WORD 


Reserved 


WORD 



Remarks 

This is done to allow the Category 9 Generic lOCtIs to be appropri- 
ately routed to the correct device driver. This call is not tied to a par- 
ticular unit that the device driver owns, but is directed to the device 
driver as a general query of its device support. 

The device driver must perform the following actions: 

• Set the count as discussed above (1 -based). 

• Set the status word in the request header. 
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17H / GET FIXED DISK/LOGICAL UNIT MAP 



Purpose 

This call is used by the system to determine which logical units 
supported by the device driver exist on physical partitionable fixed 
disk N. 



Format of Request Block 



Field 


Length 


Request Header 


13 BYTES 


Units-supported bit mask 


4 BYTES 


Reserved 


WORD 


Reserved 


WORD 



Remarks 

On entry,the request packet header unit field identifies a physical disk 
number (based on 0) instead of a logical unit number. The device 
driver returns a bit map of which logical units exist on the physical 
drive. The physical drive relates to the partitionable fixed disks 
reported to the system by way of the PARTITIONABLE FIXED DISKS 
command. It Is possible that no logical units exists on a given phys- 
ical disk because it has not yet been initialized. 

The device driver must perform the following: 

• Set the 4-byte bit mask to indicate which logical units that it owns 
exist on the physical partitionable fixed disk for which the Infor- 
mation is being requested. 

• Set the status in the request packet header. 
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17H / GET FIXED DISK/LOGICAL UNIT MAP 



The bit mask is set up as follows. A 0 means the logical unit does not 
exist and a 1 means it does. The first logical unit that the device 
driver supports is the low-order bit of the first BYTE. The bits are 
used from right to left in the diagram below starting at the low order 
bit of each following BYTE. It is possible that all the bits will be 0. 

For example, a block device driver supports five units spread over 
the two diskette drives and one partitionable fixed disk in a system. 
Unit 0 and unit 1 map to the diskette drives. Unit 2, 3, and 4 map to 
the fixed disk. For the device command, this device driver will set 
the 4-byte bit map to: 

•0000 0000 0000 0000 0000 0000 0001 1100' binary 
or 

'00 00 00 IC hex 
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Device Driver Examples 



Using PhysToVirt and UnPhysToVirt: There are some basic guide- 
lines when using the DevlHIp services for address conversion, 
PhysToVirt and UnPhysToVirt. 

• Use ES:DI whenever possible when converting a single physical 
address. 

• Use ES:DI for the first address conversion when using two phys- 
ical addresses. 

• Check the physical address pair and convert the physical address 
that lies above 1 Mb first. 

The following examples show the recommended way to use these 
DevHIps in various scenarios. These examples apply to both task- 
time and interrupt-time operations, except where noted. 

• To get a logical address to place in an ABIOS request block: 

1. Call PhysToVirt with ES:DI for the converted address. 

2. Store the converted address in the ABIOS request block. 

3. Call the ABIOS service. 

4. Call UnPhysToVirt. 

• To convert a single physical address to use as the source in a 
data transfer to a logical address, (that is, one that was passed as 
input for this data transfer request): 

1. Save DS. 

2. Call PhysToVirt with DS:SI for the converted address. 

3. Perform the data transfer. 

4. Restore DS. 

5. Call UnPhysToVirt. 
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• To provide two logical addresses in order to do a data transfer: 

1. Examine the physical address pair. If one of the physical 
addresses is above 1 MB, then convert it first. 

2. Call PhysToVIrt with ES:DI for the first address. 

3. Save DS. 

4. Call PhysToVirt with DS:SI for the second address. 

5. Perform the data transfer. 

6. Restore DS. 

7. Call UnPhysToVirt. 

• To Do multiple data transfers: 

1. Examine the first physical address pair. If one of the physical 
addresses is above 1 MB, then convert it first. 

2. Call PhysToVIrt with ES:DI for the first address. 

3. Save DS. 

4. Call PhysToVirt with DS:SI for the second address. 

5. Perform the data transfer. 

6. Restore DS. 

7. Examine the second physical address pair, if one of the phys- 
ical addresses is above 1 MB, then convert it first. 

8. Call PhysToVirt with ES:DI for the first address. 

9. Save DS. 

10. Call PhysToVirt with DS:SI for the second address. 

1 1 . Perform the data transfer. 

12. Restore DS. 

13. Perform these steps until all data transfers are complete. 

14. Call UnPhysToVirt. 
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• To provide two logical addresses for a data transfer whicli must 
be broken down into snnaller chunks In order to YIELD 
periodically: 

1. Exannlne the physical address pair. If one of the physical 
addresses Is above 1 MB, thien convert it first. 

2. Call PhysToVirt with ES:DI for the first address. 

3. SaveDS. 

4. Call PhysToVirt with DS:SI for the second address. 

5. Perform the data transfer on the chunk. 

6. Restore DS. 

7. Call UnPhysToVirt. 

8. YIELD. 

9. When control Is returned, repeat these steps. 

• To pass two logical addresses to a subroutine, one of which must 
be converted from a physical address, the other is obtained from 
the device driver's data segment: 

1. Examine the physical address pair. If one of the physical 
addresses Is above 1MB, then convert it first. 

2. Call PhysToVirt with ES:DI for the address to convert. 

3. Save the converted address in the appropriate input param- 
eter to the subroutine. 

4. Save the other logical address (located in the device driver's 
data segment) in the appropriate input parameter to the sub- 
routine. 

5. Call the subroutine. 

6. Call UnPhysToVirt. 
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To use two logical addresses to do a data transfer at Interrupt 
time before the EOl: 

1. Examine the physical address pair. If one of the physical 
addresses is above 1 MB, then convert it first. 

2. Call PhysToVirt with ES:DI for the first address. 

3. Save DS. 

4. Call PhysToVirt with DS:SI for the second address. 

5. Perform the data transfer. 

6. Restore DS. 

7. Call UnPhysToVlrt. 

8. Issue the EOl. 

To use two logical addresses in order to do a data transfer at 
interrupt time after the EOl: 

1. Issue the EOl. 

2. Examine the physical address pair. If one of the physical 
addresses Is above 1 MB, then convert it first. 

3. Save the interrupt flag. 

4. Disable interrupts. 

5. Call PhysToVirt with ES:DI for the first address. 

6. Save DS. 

7. Call PhysToVirt with DS:SI for the second address. 

8. Perform the data transfer. 

9. Restore DS. 

10. Restore the interrupt flag. 

11. Call UnPhysToVirt. 



Notes On Writing a Device Driver using Advanced BIOS 

The following Is a high-level example of how a device driver would be 
written to use Advanced BIOS. 

To determine the basic structure of the device driver, certain design 
points must be identified. 

• The kind of device to be supported (character or block). 

• The nature of the I/O to the device (synchronous or staged, 
Program I/O (PIO) or Direct Memory Access (DMA)). 

A staged request can be further refined to be staged on a time 
delay, staged on an interrupt or both. Staged on a time delay 
means the operation involves waiting for a specific length of time 
before the operation can be continued or is completed. Staged 
on an interrupt means the operation Involves waiting for an inter- 
rupt to occur. 

PIO or DMA refers to the type of addressing required for data 
transfers. PIO is done using virtual addresses (which are also 
referred to as logical addresses) of the form: 

segment/sel ector: offset . 

DMA is done using physical addresses which are 32-bit numbers 
indicating the data transfer location in memory. 

• The maximum number of devices. 

• The maximum number of interrupt levels. 

These items determine the nature of the device driver, that is, how 
the task-time and interrupt-time portions of the device driver relate to 
each other and which of the DevHIp services will be used for 
blocking, queueing, timers, and others. 
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Note that the type and number of devices generally indicate the 
logical device names (for example, C0M1, LPT1) that the device 
driver will support. 

• A device type is identified by its ABIOS-archltected device ID. 

• A specific device Is Identified by a Logical ID (LID) and unit 
number under that LID. 

• I/O to the device is performed by calling the ABIOS entry point 
(Start, Interrupt, or Timeout) that corresponds to the particular 
LID. 

• Parameters are passed to an ABIOS service through a request 
block structure. 

• I/O requests can be synchronous (run to completion), or staged 
(run until blocked, waiting for an interrupt or time). 

• Staged requests may have well-defined time delays between 
certain stages. 

• Data transfers may use either virtual addresses 

(segment/sel ector:of f set) 
or physical addresses. 

Before using ABIOS services and during initialization, a device driver 
must identify every LID for which It will accept requests. To do this, 
the device driver uses the architected ABIOS Device ID for its device. 
The device driver uses the DevHIp GetLIDEntry, which searches 
through the Advanced BIOS common data area looking for the LID 
that corresponds to the given device ID. 

In general, by making repeated calls to GetLIDEntry and counting the 
number of units supported by each LID it obtains, the device driver 
determines how many supported devices are configured in the 
system. The device driver will only process interrupts and requests 
for its maximum number of supported devices. Any LID of the device 
driver's device type that is leftover must be unclaimed so another 
device driver can support It. 
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A device driver l<nows wliicli LID corresponds to a given logical 
device nanne (for example, C0M1) because of the rule forcing the 
operating system logical device names to be in the same order as the 
LID entries for an associated device ID. 

For example, assuming one unit per LID, then an installable printer 
device driver will support LPT3 (the third printer) by locating the third 
LID that corresponds to device ID of printer (that is "awake"). 

The device driver must determine which Interrupt level each LID will 
use by using the ABIOS function, Return LID Parameters. The device 
driver will register Interrupt handler entry points for the Interrupt 
levels that it supports with the DevHIp SetlRQ. It keeps a list of every 
LID that corresponds to each interrupt handler. 

Note: If the device driver supports multiple devices and the number 
of interrupt levels for those devices exceed the number of supported 
Interrupt levels, the device driver will ignore any LID that it cannot 
support because too many different interrupt levels are required. 

At task time, when the device driver strategy entry point for a given 
device header receives a request packet, the device driver knows 
which logical device name and LID (and unit number) correspond to 
that entry point. 

The device driver strategy routine sets up an ABIOS request block 
and uses the DevHIp ABIOSCall to invoke the Advanced BIOS START 
routine to begin the requested ABIOS function. ABIOS requires that 
the ReturnCode field in the ABIOS request block be initialized to 
FFFFH. ABIOS will set the ReturnCode to its appropriate value. 

Note: Either portion of the device driver, the task-time strategy 
routine or the interrupt handler, may start an ABIOS request. For 
simplicity, the example will use the strategy routine as the caller of 
the Advanced BIOS START service. 

The pointer to the ABIOS request block and any logical data transfer 
pointers can be set up by the device driver independent of mode if the 
data transfer areas are in the device driver's data segment. 

(segment/sel ectorroff set) 
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If the data transfer is to take place to a logically addressed buffer in a 
bimodal environment, the device driver will need to double buffer the 
data transfer if the target location of the data could be high memory 
while running in real mode or if the device driver needs to run 
enabled. That is, the device driver should use an intermediate buffer 
located in its data segment (which is below 1 MB) for the data 
transfer performed by ABIOS. The device driver would then complete 
the data transfer to the user data buffer itself. 

In a multi-staged request, the address of the logically addressed data 
buffer may have to be changed by the device driver in the Advanced 
BIOS request bloclcfrom stage to stage. This is normal because of 
the bimodal characteristics of the operating environment. For 
devices that require physical address data transfer (for example, 
DMA-oriented devices), the device driver must ensure that the buffer 
area is locked for the duration of all stages of the request. 

Interrupt during START: If the request is staged on an interrupt then 
ABIOS will set the ReturnCode appropriately only when the par- 
ticular service is ready to be resumed through the Advanced 
BIOS INTERRUPT routine. The device driver strategy routine 
must also set a flag to indicate whether a request has com- 
pleted the START request to the point at which the strategy 
routine interrogates the ReturnCode. This must be done to 
accommodate the case where the interrupt occurs after ABIOS 
updates the ReturnCode, but before the device driver strategy 
routine interrogates the ReturnCode. In this case, the device 
driver Interrupt handler is invoked by the interrupt and can take 
appropriate action on the request block, even though the device 
driver strategy routine has not completed processing the 
request block. 

For example, if the strategy routine is expected to BLOCK the 
request until the interrupt occurs, but the interrupt handler is 
invoked before the strategy routine is able to BLOCK, the inter- 
rupt handler needs to flag the fact that the interrupt handler 
already processed the request block. The strategy routine, 
when it gets control, will then see that it should not check the 
ReturnCode in the request block and it does not have to BLOCK 
because the request is already completed. The strategy routine 
will set up the request packet with the return information and 
return the completed request to the kernel. 
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This example would be more complex if, when the strategy 
routine got control, the request was still incomplete (as would 
occur in a multi-staged request). The strategy routine would 
still ignore the ReturnCode because the request block would 
already be at a different stage (than the START) but the strategy 
routine may still have to BLOCK. 

Interrupt after START: For a staged ABIOS request that must wait for 
the interrupt associated with the specified LID to occur after the 
request is STARTed, the ReturnCode of the request will be set 
to stage-on interrupt by the ABIOS START function. This indi- 
cates that the request is incomplete. Several requests for this 
LID may START and be waiting for the device interrupt. These 
incomplete requests are commonly referred to as outstanding 
requests for the LID. 

Note: The request Is considered to be an outstanding request for the 
LID, even If the START service has not returned control to the caller 
of the START service. 

A device driver never assumes that the return codes for an ABIOS 
request occur in any given order. The ReturnCode should always be 
checked to determine what actions to perform on the request block. 

When the device driver interrupt handler is invoked by the device 
interrupt, it knows which LID is associated with the interrupt level. 
The interrupt handler must individually examine each LID associated 
with the interrupt level. For a LID, the interrupt handier must process 
all outstanding staged-on interrupt request blocks. That is, the Inter- 
rupt handler is required by ABIOS to call the Advanced BIOS INTER- 
RUPT routine for every outstanding staged-on interrupt request block 
to completely process one LID. This includes a START request block 
in which the ReturnCode has been changed from FFFFH to stage-on 
interrupt but where the START service has not yet returned control to 
its caller. If one of the request blocks for the LID caused the interrupt, 
then after the interrupt handler has called ABIOS with ail the out- 
standing request blocks owned by this LID, the interrupt handler will 
not need to process any other LID associated with this interrupt level. 
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if a given LiD has no outstanding ABiOS request bloci<s, tlie device 
driver will call tfie Advanced BIOS DEFAULT INTERRUPT service for 
that LID. Tlie DEFAULT INTERRUPT service will reset the interrupt 
condition for that LID if the LID falsely caused the interrupt. It will 
then return to the device driver interrupt handler, indicating that the 
interrupt belonged to the LID. 

If there Is at least one outstanding ABIOS request block for a given 
LID, ABIOS will automatically invoke the DEFAULT INTERRUPT 
service if the LID generates a false interrupt. The device driver must 
be able to process the false interrupt return code for any call to the 
ABIOS INTERRUPT routine. This return code indicates that the inter- 
rupt belonged to the LID, was reset by ABIOS, and the device driver 
is responsible for issuing the EOl and returning to the operating 
system as owning the interrupt. The device driver is still responsible 
for calling ABIOS with any remaining staged-on-interrupt request 
blocks for this LID. 

The device driver interrupt handler may issue the EOl (via the DevHIp 
EOl function) only after completely processing the LID that owns the 
interrupt or after the LID's DEFAULT INTERRUPT service indicates 
that the LID's device caused the interrupt. In other words, the Inter- 
rupt handler must process all outstanding requests under the LID that 
owns the interrupt, even after finding a request block which indicates 
that it caused the interrupt. The interrupt handier may stop proc- 
essing any LID for this interrupt only when the interrupt is claimed by 
a LID, either by a request under the owning LID or by the owning 
LID'S DEFAULT INTERRUPT service. 

The interrupt handler knows that once it issues the EOl after com- 
pletely processing a LID, another LID requesting service at the 
current interrupt level, would create another interrupt. 

Once the EOl is issued, the interrupt handler can be reentered at its 
entry point. If the Interrupt handler is reentered, it must process 
every LID, including the one that is near completion or just com- 
pleted. 

In order to keep the pre-EOI processing time to a minimum, the inter- 
rupt handler may wish to issue its EOl either before it sets the return 
information in the operating system request packet, or before it 
begins processing a request packet that was queued by the device 
driver strategy routine. 
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If the interrupt handler did not find any LID that claimed the given 
interrupt either with a request blocic or by a DEFAULT INTERRUPT 
service, the interrupt handler must exit, indicating that the Interrupt 
did not belong to it; that is, it was not caused by any LID that the 
device driver owns. 

Eventually, the ReturnCode from ABIOS will show that the ABIOS 
request block is complete. The device driver can then clean up the 
device driver request packet queue and take the next request pack9t 
and try to start another ABIOS request block. 

The device driver will support the timeout requirements of Advanced 
BIOS with the DevHIp SetTlmer and the DevHIp TickCount. Instead of 
counting every clock tick, the device driver will use TickCount to force 
its timer tick entry point to receive control as infrequently as possible. 
The design of the Advanced BIOS TIMEOUT function is In 1-second 
increments. 

Device drivers in an Advanced BIOS environment have the same 
requirement to support DOS mode operations as they do in OS/2. In 
addition, for certain devices such as diskette and disk, the device 
driver must reset the device when switching between Advanced BIOS 
operation and BIOS operation. This is because state of the device 
information lis kept internally to the Advanced BIOS and BIOS device 
blocks, which would get out of synchronization if the device were not 
reset when switching between the two sets of code. 
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Chapter 8. Device Helper Services 



Many of the functions of an OS/2 device driver are related to system 
operations rather than to hardware operations. Therefore, an inter- 
face to operating system services is therefore available to device 
drivers through the DevHIp interface. 

Access to these system services is obtained at the time of device 
driver initialization. The request packet for the INIT command con- 
tains a pointer to the DevHIp interface. The pointer to the DevHIp 
interface is a bimodal pointer; that is, this pointer to the DevHIp inter- 
face is valid in both the DOS mode and the OS/2 mode. The device 
driver does not have to be sensitive to the mode of operation before 
requesting DevHIp services. 

The DevHIp services are listed below. A service is invoked by setting 
up the appropriate registers, loading a function code into the DL reg- 
ister, and making a FAR CALL to the DevHIp interface routine, whose 
address was supplied at device driver initialization time. 



DevHIp Services and Function Codes 



DevHIp Service 


Code 


Description 


SchedClockAddr 


0 


Get system clock routine 


DevDone 


1 


Device I/O complete 


Yield 


2 


Yield the CPU 


TCYield 


3 


Yield the CPU to time-critical 


Block 


4 


Block thread on event 


Run 


5 


Unblock thread 


SemRequest 


6 


Claim a semaphore 


SemClear 


7 


Release a semaphore 


SemHandle 


8 


Get a semaphore handle 


PushReqPacket 


9 


Add request to list 


PullReqPacket 


A 


Remove request from list 


Pull Particular 


B 


Remove a specific request from list 


SortReqPacket 


0 


Insert request in sorted order to list 
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DevHIp Service 


Code 


Description 


AllocReqPacket 


D 


Get a request packet 


FreeReq Packet 


E 


Free request packet 


Queuelnit 


F 


Initialize character queue 


QueueFlush 


10 


Clear character queue 


QueueWrite 


11 


Put a character in the queue 


QueueRead 


12 


Get a character from the queue 


Lock 


13 


Lock segment 


Unlock 


14 


Unlock segment 


PhysToVirt 


15 


Map physical-to-virtual address 


VIrtToPhys 


16 


Map virtual-to-physical address 


PhysToUVirt 


17 


Map physical-to-user virtual 


AllocPhys 


18 


Allocate physical memory 


FreePhys 


19 


Free physical memory 


SetROMVector 


1A 


Set Software interrupt vector 


SetlRQ 


IB 


Set a hardware interrupt handler 


UnSetlRQ 


1C 


Reset a hardware interrupt handler 


SetTimer 


ID 


Set a timer handler 


ResetTimer 


IE 


Remove a timer handler 


MonitorCreate 


IF 


Create a monitor 


Register 


20 


Install a monitor 


DeRegister 


21 


Remove a monitor 


MonWrite 


22 


Pass data records to monitor 


MonFlush 


23 


Remove all data from stream 


GetDOSVar 


24 


Return pointer to DOS variable 


SendEvent 


25 


Indicate an event 


ROMCritSection 


26 


ROM BIOS critical section 


Verify Access 


27 


Verify memory access 


Reserved 


28 




Reserved 


29 




Reserved 


2A 




Reserved 


2B 




Reserved 


2C 




AllocGDTSelector 


2D 


Allocate GDT Selectors 


PliysToGDTSelector 


2E 


Map physical to virtual address 


RealToProt 


2F 


Real Mode to Protect Mode 


ProtToReal 


30 


Protect Mode to Real Mode 


EOl 


31 


Issue an End-Of-lnterrupt 
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DevHIp Service 


Code 


Description 


UnPhysToVirt 


32 


Mark PhysToVirt complete 


TIckCount 


33 


Modify timer 


GetLIDEntry 


34 


Get Logical ID 


FreeLIDEntry 


35 


Release Logical ID 


ABiOSCall 


36 


Invoke ABIOS function 


ABiOSCommonEntry 


37 


Invoke ABIOS Common Entry Point 


Reserved 


38 





As discussed in the section on device driver arciiitecture, device 
driver code may run in one of four contexts. 

• Kernel mode - the context in which the device driver strategy 
routine runs. 

• interrupt mode - the context in which the device driver hardware 
interrupt handler runs. 

• User mode - the context in which the device driver handier for a 
DOS mode software interrupt runs. 

• Init mode - the context In which the device driver Strategy routine 
runs when it is called with the INIT request packet. 



DevHIp Services and Corresponding States 

Certain restrictions apply as to when individual DevHIp services can 
be used. The following list outlines which DevHIp services are 
allowed in which contexts (kernel, interrupt, user, or initialization). 



DevHIp Service 


Code 


Kernel 


interrupt 


User 


Init 


SchedClockAddr 


0 


* 






* 


DevDone 


1 


* 


* 






Yield 


2 


* 








TCYield 


3 


* 








Block 


4 


* 




* 
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DevHiD Service 


CodG 


Kernel 


interruDt 


UsGr 


Init 


Run 


5 


* 


* 


* 




SemReauest 


6 


* 




* 




SemClear 


7 


* 


* 


* 




SemHandle 


8 


* 


* 






Push Rea Packet 


9 


* 








PullReaPacket 

1 dill swVII MWIXwi 


A 


* 


* 






PullParticular 


B 


* 


It 






SortReaPacket 


c 


* 








AllocReaPacket 


D 


* 








FreeReaPacket 


E 


* 








Qu6U6lnit 


F 


* 


* 


* 


* 


OueueFlush 


10 


* 


* 


* 




OueueWrite 


-j-j 


♦ 


* 


* 




OueueRead 


12 


* 


* 


* 




Lock 


13 


* 








Unlock 


14 


* 






* 


PhysToVirt 


16 


* 


* 




* 


VirtToPhvs 

V 1 1 L 1 \jt 1 1 y w 


16 


* 






* 


PhvsToUVIrt 


"17 


* . 








AllocPhys 


18 


* 






* 


FreePhvs 

1 1 wwi 1 1 y w 


19 


* 






* 


SetROMVector 


1A 


* 






* 


SetlRQ 


1B 


* 






* 


UnSetlRQ 


1C 


* 


* 




* 
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DevHIp Service 


Code 


Kernel 


Interrupt 


User 


Init 


SetTimer 


ID 


* 






* 


ResetTimer 


IE 


* 


* 




* 


MonitorCreate 


1F 


* 






* 


Register 


20 


* 








DeRegister 


21 


* 








MonWrite 


22 


* 


* 


* 




MonFlush 


23 


* 








GetDOSVar 


24 


* 






* 


SendEvent 


25 


* 


* 






ROMCritSection 


26 






* 




VerifyAccess 


27 


* 








AilocGDTSelector 


2D 








* 


PhysToGDTSelector 


2E 


* 


* 


* 


* 


RealToProt 


2F 




* 






ProtToReal 


30 




* 






EOl 


31 




* 




* 


UnPhysToVirt 


32 


* 


* 




* 


TickCount 


33 


* 


* 


* 


* 


GetLIDEntry 


34 


* 






* 


FreeLIDEntry 


35 


* 






* 


ABIOSCall 


36 


* 


* 


* 


* 


ABIOSCommonEntry 


37 


* 


* 


* 


* 
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Related DevHIp services are grouped together in the following cate- 
gories. 

1. System Clock Management 

• SchedClockAddr 

2. Process Management 

• Block 

• DevDone 

• Run 

• TCYield 

• Yield 

3. Semaphore Management 

• SemClear 

• SemHandle 

• Sem Request 

4. Request Queue Management 

• AllocReqPacket 

• FreeReqPacket 

• PullParticular 

• PullReqPacket 

• PushReqPacket 

• SortReqPacket 
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5. Character Queue Management 

• QueueFlush 

• Queuelnit 

• QueueRead 

• QueueWrite 

6. Memory Management 

• AllocGDTSelector 

• AllocPhys 

• FreePhys 

• Lock 

• PhysToGDTSelector 

• PhysToUVirt 

• PhysToVirt 

• Unlock 

• UnPhysToVIrt 

• VerifyAccess 

• VirtToPhys 

7. Interrupt Management 

• EOl 

• SetlRQ 

• SetROMVector 

• UnSetlRQ 

8. Timer Services 

• ResetTimer 

• SetTlmer 

• TIckCount 



9. Monitor Manag9ment 

• DeRegister 

• MonFlush 

• MpnitorCreate 

• MonWrjte 

• Register 

10. System Services 

• GetDOSVar 

• SendEvent 

• ROMCritSection 

11. Processor Mode Services 

• ProtToReal 

• RealToProt 

12. Advanced BIOS Services 

• ABIOSCaii 

• ABIOSCommonEntry 

• FreeLIDEntry 

• GetLiDEntry 



8-8 



DevHIp Interfaces 



Calling conventions for eacli of the DevHIp services follow. In addi- 
tion to tlie explicit effects noted under eacli service, tlie interrupt flag 
can be set or cleared by some services, and other flags can be 
affected by the calls. Some services require that the interrupt flag be 
off when they are called. 

The device driver can assume that the state of the interrupt flag will 
be preserved, and that the DevHIp routine will not enable interrupts 
unless stated otherwise in the functional description for each routine. 
The only exceptions apply to functions that allow the device driver to 
relinquish control of the CPU. Therefore, during calls to functions 
such as Yield and TCYield, the device driver cannot assume that 
interrupts will remain disabled. 

All registers except flag registers are preserved across DevHIp calls 
unless specified as containing return parameters. 

The functional descriptions for the DevHIp services follow in alpha- 
betical order. 
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ABIOSCall 

Invoke ABIOS function 



Purpose 

This routine is used to invoice an ABIOS service for the Operating 
System Transfer Convention. 

Processing 



MOV DL,DevHlp_ABIOSCall 
CALL [Device_Help] 

Results 

'C Clear if no error 
ABIOS service invoked. 

'C Set if error 
AX = error code 



Remarks 

The stack is set, depending on the current address mode, for the call 
to ABIOS, and the indicated ABIOS function is called according to the 
Operating System Transfer Convention. Refer to Operating System 
Transfer Convention on page 7-33. When the ABIOS function returns, 
ABIOSCall will clean up the stack before returning to the device 



MOV AX. LID 

MOV SI.RB^Offset 



Logical ID 

Offset In data segment 
to ABIOS request block 
Specifies entry point 

0 = start 

1 = interrupt 

2 = timeout 



MOV DH,Entry_Point 



ABIOS not present. 
Unknown ABIOS Command 



driver. 
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ABIOSCall 
Invoke ABIOS function 



Note: Advanced BIOS functions called in user mode may need to be 
protected from being suspended in the background. This will occur 
when the DOS mode Is In the foreground and the user selects an 
OS/2 mode application to run. The DOS mode will be suspended. To 
protect the ABIOS function, the device driver should issue the DevHIp 
call ROMCritSection. 

Note that DS must point to the device driver's data segment. If DS had 
been previously used in a PhysToVirt call, it must be reset to the 
device driver's data segment. 
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ABIOSCommonEntry 

Invoke ABIOS Common Entry Point 



Purpose 

This service is used to invoke an ABIOS Common Entry Point 
according to the Advanced BIOS Transfer Convention. 



Processing 

MOV SI.RB_Offset 



MOV DH,Entry_Point 



; Offset in data segment 
to ABIOS request block 
; Specifies entry point 

0 = start 

1 = interrupt 

2 = timeout 
DL,DevH1p_ABI0SCommonEntry 



MOV 

CALL [Device_Help] 



Results 

'C Clear if no error 

ABIOS service invoiced. 
'C Set if error 
AX = error code 

ABIOS not present. 
Unknown ABIOS Conmand 



Remarks 

ABIOSCommonEntry sets up the stack, depending on the current 
address mode, for the call to one of the Advanced BIOS Common 
Entry Points. It then invokes the indicated ABIOS common entry 
point. On return from the ABIOS function, the ABIOSCommonEntry 
cleans up the stack before returning to the device driver. 
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ABIOSCommonEntry 
Invoke ABIOS Common Entry Point 



Note: Advanced BIOS functions called In user mode may need to be 
protected from being suspended in the background. This will occur 
when the DOS mode is foreground and the user selects an OS/2 
mode application to run. The DOS mode will be suspended. To 
protect the ABIOS function, the device driver should issue the DevHIp 
call ROMCritSectlon. 

Note that DS must point to the device driver's data segment. If DS had 
been previously used in a PhysToVirt call, it must be reset to the 
device driver's data segment. 



8-13 



AllocGDTSelector 
Allocate GDT Selectors 



Purpose 

This function allocates a set of GDT selectors for a device driver to 
use. This allocation is performed at device driver INIT time. 

Processing 

MOV ES,address_high ; 32-bit address of GDT 

MOV DI,address_low ; selector array 

MOV CX, number ;Number of selectors requested 

MOV DL.DevHlp.AllocGDTSelector 

CALL [Device_Help] 

Results 

'C Cleared if successful 
'C Set if error 
AX = error code 

Inval id address 

Zero selectors requested 

Not enough selectors available 

Remarks 

AllocGDTSelector is used to allocate a set of GDT selectors for a 
device driver to use for bimodal task-time and interrupt-time oper- 
ations. 

The address passed in ES:DI gives the location of an array of words 
to be filled in with the GDT selectors allocated. The value of CX spec- 
ifies the number of selectors to be allocated. Note that the selector 
values returned may not be contiguous values. 

A bimodal device driver supports both real mode and protect mode 
I/O and must be able to transfer data without being dependent on the 
current mode of operations. In addition, the interrupt handler of a 
bimodal device driver must be able to address data buffers regard- 
less of the context of the current process (the current LDT will not 
necessarily address the data space that contains the data buffer that 
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AllocGDTSelector 
Allocate GDT Selectors 



the interrupt handler needs to access). The PhysToGDTSelector func- 
tion is used to establish the addressability of a GDT selector, and the 
GDT selector's addressability will remain valid and the same until 
another PhysToGDTSelector call is made for the same selector. 

The RealToProt function is used to change processor mode from real 
mode to protect mode, and the ProtToReal function is used to return 
the processor to real mode. The device driver must always return the 
processor to the same mode it was in when entered if either the 
ProtToReal or RealToProt functions are used. 
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AllocPhys 

Allocate Fixed Block of Physical Memory 



Purpose 

AllocPhys is used by device drivers to allocate a block of fixed 
memory. 

Processing 

MOV BX.sizeJow 
MOV AX,size_high 
MOV DH,higli_orJow 



MOV DL.DevHIp.AllocPhys 
CALL [Device_Help] 

Results 

'C Clear if memory allocated 

AX:BX = 32-bit physical addreiss. 
'C Set if memory not allocated 

AX = error, memory not allocated. 

Remarks 

The memory allocated by this function is fixed memory, and may not 
be "unfixed" via the Unlock call. 

If memory is requested to be allocated high (above 1 megabyte), and 
no memory above 1 megabyte is available, then ah error is returned. 
The device driver could then attempt to allocate low memory. 

Conversely, if memory is requested to be allocated low (below 1 
megabyte), and no memory below 1 megabyte is available, then an 
error is returned and the device driver could try allocating high 
memory, if appropriate. 



;size in bytes 

; Relative position to 1 megabyte 
; - 0 above 1 megabyte 
; = 1 below 1 megabyte 
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AllocReqPacket 
Get a Request Packet 



Purpose 

This service returns a pointer to an empty request packet. 
Processing 

MOV DH,wait_flag ;Wait for available 

; request packet 
;= 0 if to wait 
;= 1 if not to wait 

MOV DL,DevHlp_AllocReqPacl(et 
CALL [Device_Help] 

Results 

'C Cleared if a request packet was allocated. 
ES:BX is the virtual address of 
the allocated request packet. 
'C Set if a request packet was not allocated. 

Remarks 

AllocReqPacket returns a blmodal pointer to a maximum size request 
packet. The bimodal pointer is a virtual address that is valid for both 
the DOS mode and the OS/2 mode. 

Some device drivers, notably the disk device driver, need to have 
additional request packets to service task-time requests. Because 
device drivers are bimodal, they cannot use a packet residing in their 
data segment because the resulting pointer is not bimodal. 

Request packets that were allocated by an AllocReqPacket may be 
placed in the request packet linked list. 
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AllocReqPacket 
Get a Request Packet 



Request packets allocated in this manner should be returned to the 
kernel as soon as possible via the FreeReqPacket function. The 
system as a whole has a limited number of request packets, so it is 
important that a device driver not allocate request packets and hold 
them for future use. 

The state of the interrupt flag is not preserved across calls to this 
DevHIp. 
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Block 

This Thread From Running 



Purpose 

This service "sleeps" the thread executing in the device driver until 
either the Run call is issued on the event identifier or a timeout 
occurs. 

Processing 

MOV BX.eventJdJow 

MOV AX,eventJd_liigh 

MOV DI,timeJimit_high 

MOV CX.timeJimitJow 

MOV DH,interruptible_flag 

MOV DL,DevHlp_Block 
CALL [Device_Help] 

Results 

'C Clear if event wakeup. 
'C Set if unusual wakeup. 
'Z' Set if wakeup due to timeout. 
'Z' Cleared if sleep was interrupted. 
AL Awake code, non-zero if unusual wakeup. 
Interrupts enabled. 

Remarks 

The return from the Block call indicates whether the "wakeup" 
occurred from a normal of Run call or an expiration of the time limit. 

Block removes the current thread from the run queue and starts exe- 
cuting some other thread. The thread blocked in the device driver is 
reactivated and Block returns when Run is called with the same 
event identifier, when the time limit expires, or when the thread is 
signalled. 



Low word of event id 
High word of event id 
Timeout interval 
in milliseconds 

= -1 if to never timeout 
Tells if sleep is interruptible 

= 0 interruptible 

= 1 non-interruptible 
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Block 

This Thread From Running 



The event identifier is an arbitrary 32-bit value, but a convention must 
be followed to coordinate witli the thread issuing the Run function. 
The standard convention for Block/Run operations Is to use the 
address of some structure or memory cell associated with the reason 
for blocking and running. For example, a thread blocking until some 
resource is cleared normally blocks "on" the address of the owner- 
ship flag for that resource. 

Because dual-mode device drivers may be Blocked in one mode and 
Run in the other, using the virtual address as the event identifier is 
not sufficient; the virtual address of an item in one mode Is not the 
same as its virtual address In the other mode. A possible option for a 
device driver is that it Blocks/Runs on the 32-blt address of a request 
packet being processed for the thread. 

The Block/Run mechanism is so designed that it cannot guarantee 
immunity from a faulty wakeup by some other thread in the system 
running a 32-bit key value, which happens to match some unrelated 
blocking thread's key. The goal Is to choose keys which can be 
known to the Blocker and the Runner and have a high likelihood of 
being unique. Users of Block/Run must always check the reason for 
their wakeup to make sure that the event really took place and that 
the wakeup wasn't accidental. 

When calling Block it is important to use the sequence: 

Disable Interrupts 
while (need to wait) 

Block (value) 

Disable Interrupts 

Interrupts are turned off before checking the condition (I/O done, 
resource freed, whatever) first to avoid a deadlock by getting an 
interrupt-time Run call before completing the call to Block. Block 
reenables the interrupts. Also note the "while" clause, it is essential 
to recheck the awaited condition and, if necessary, re-disable inter- 
rupts and re-call Block. The convention of using an address as an 
event identifier should prevent double use of an identifier. 
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Block 

This Thread From Running 



A time limit of -1 means that Block waits indefinitely until Run is 
called. Block can only be called by the task-time portion of a device 
driver. 

When using Block to block a thread, the driver can specify whether 
or not the sleep may be interrupted. If the sleep is interruptible, then 
the kernel can abort the blocked thread and return from the Block 
without using a corresponding Run. In general, the sleep should be 
marked as interruptible unless the sleep duration is expected to be 
short, that Is, less than a second. 

If the return from the Block indicates that the sleep was interrupted, 
that means that some Internal event occurred that requires attention 
(like a signal, process death, or some other forced action). The 
device driver should respond by performing any necessary cleanup, 
setting the error code In the status field of the request packet, setting 
the done bit, and returning the request packet to the kernel. 
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DeRegister 
Remove Monitor 



Purpose 

DeRegister removes all of the monitors associated with the specified 
tasl< from the specified monitor chain. 

Processing 

MOV BX,monitor_PID ; Process ID of monitor task 

MOV AX,monitor_handle ; Moni torCreate handle for cliain 

MOV DL,DevHlp_DeRegister 
CALL [Device_Help] 

Results 

'C Clear if OK 

AX = # of monitors still registered in cliain, 
after Deregi strati on. 
'C Set if error 
AX = error code 

Invalid monitor handle 

Remarks 

This function may only be called at task time In the OS/2 mode. 

To remove a monitor from a monitor chain, the device driver must 
supply the PID of the process that owns the monitor being removed 
and the handle of the monitor chain that Is affected. All monitors 
belonging to the specified PID are removed from the monitor chain. 

A single process may register more than one monitor with the same 
monitor chain. Therefore, DeRegister removes all monitors associ- 
ated with the specified process from the specified monitor chain. 
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DevDohe 
Flag I/O Complete 



Purpose 

This function signifies that a request has completed and unblocks any 
threads waiting in the kernel for the request. 

Processing 

LES BX,request_paclcet ;Pointer to I/O request 

; packet. 

MOV DL.DevHlp_DevDone 
CALL [Device_Help] 

Results 

None 

Remarks 

This service will set the "done" bit in the status field of the request 
packet header and issue RUNs on thread(s) which are blocked in the 
kernel waiting for the request packet to be completed. DevDone is 
called from the device interrupt routine. The device driver should set 
any error flags in the status field before calling the routine. 

Because the virtual address of a request packet is bi modal (the 
virtual address is valid in both the DOS mode and the OS/2 mode), 
the device driver may pass the request packet pointer to DevDone 
without being sensitive to the mode of operations. 

DevDone does not apply to request packets that were allocated from 
the AllocReqPacket function call. 

The device driver does not have to call DevDone for requests that are 
completed at task time (In the strategy routine). Requests that are 
completed at strategy time should return with the done bit set in the 
request packet. 
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EOl 

Issue an End-OMnterrupt 



Purpose 

This routine is used to issue an End-OMnterrupt to the master/slave 
8259 interrupt controller(s) as appropriate to the interrupt level. 

Processing 

MOV AL.IRQnum ; Interrupt level number 

; ( 0 - F ) 

MOV DL,DevHlp_EOI 
CALL [Device_Help] 

Results 

None 

Remarks 

This routine is used to issue an End-Of-lnterrupt to the 8259 interrupt 
controller(s) on behalf of a device driver interrupt handier. If the spec- 
ified interrupt level is for the slave 8259 interrupt controller, then this 
routine will issue the EOl to both the master and slave 8259s. 

Device drivers must use this service in their interrupt handlers for 
upward compatibility. 

Note that this routine Is callable at Init-time for interrupt processing. 

This DevHip does not change the state of the interrupt flag. If the 
device driver returns to the operating system immediately after 
issuing the EOl, then it should disable interrupts prior to the EOl. Dis- 
abling interrupts prior to issuing the EOl allows the processing for 
this interrupt level to be completed before the system services the 
next Interrupt. This reduces the probability of excessive nested inter- 
rupts causing a system Stack overflow. 
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EOl 

Issue an End-Of-lnterrupt 

If any post EOi work is done by the INT handler, It should be limited to 
the first or non-nested interrupt. Nested INT processing should be 
done only prior to the EOI. 
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FreeLIDEntry 
Release a Logical ID 



Purpose 

This routine is used to release a Logical ID. This must be done at 
DEINSTALL or termination time. 

Processing 

MOV AX, LID -.Logical ID from 

; GetLIDEntry 

MOV DL.DevHlp_FreeLIDEntry 
CALL [Device_Help] 

Results 

'C Clear if no error 
'C Set if error 
AX = Error Code 

Not your LID. 

LID does not exist. 

ABIOS not present. 

Remarks 

The attempt to free a Logical ID may fail if the device driver does not 
own the LID or if the LID does not exist. 

Note that DS must point to the device driver's data segment. If DS 
was previously used in a PhysToVirt call, it must be reset to the 
device driver's data segment. 
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FreePhys 
Free Physical Memory 



Purpose 

FreePhys is used to release memory allocated by the AllocPhys call. 
Processing 

MOV BX.addressJow ;32-bit physical address 

MOV AX.address_high ; 
MOV DL,DevHlp_FreePhys 
CALL [Device_Help] 

Results 

'C Cleared if memory freed 
'C Set if memory not freed 

Cannot free memory not allocated with AllocPhys. 

Remarks 

Any memory that the device driver allocated by way of the AllocPhys 
should be released prior to device driver termination. 
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FreeReqPackQt 

Free an Allocated Request Packet 



Purpose 

This service is used to release a request packet previously allocated 
by AllocReqPacket 

Processing 

LES BX,request_packet ; Pointer to request packet 

; previously allocated. 

MOV DL,DevHlp_FreeReqPacket 
CALL [Device_Help] 

Results 

None 

Remarks 

The device driver should only free a request packet that had been 
previously allocated by AllocReqPacket. The DevDone service 
should not be used to return an allocated request packet. 

The system as a whole has a limited number of request packets, so it 
is important that a device driver not allocate request packets and 
hold them for future use. 

The state of the interrupt flag is not preserved across calls to this 
DevHIp. 
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GetPOSVar 

Get Address of Important DOS Variables 



Purpose 

Returns the address of a kernel variable. 
Processing 

MOV AL.varnumber ; Variable wanted. 

MOV DL.DevHlp_6etD0SVar 
CALL [Device_Help] 

Results 

'C Cleared if no error 

AX:BX points to the variable. 
'C Set if error 

Remarks 

The following is the list of read only variables: 
Index Description of variable 

1 SyslNFOseg:WORD 

Bimodal segment address of the System Global InfoSeg. Valid 
at both task time and interrupt time. 

2 LoclNFOseg:DWORD 

Selector/Segment address of the local (LDT) INFO segment. 
Valid only at task time. 

3 Reserved 

4 VectorSDFrDWORD 

Pointer to the stand-alone dump facility. Valid at both task 
time and interrupt time. 

5 VectorReboot:DWORD 

Pointer to restart the OS/2. Valid at both task time and inter- 
rupt time. 
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GetDOSVar 

Get Address of Important DOS Variables 



6 Reserved 

Pointers to the MSATS facility, OS/2 mode and DOS mode. 
Valid at both task time and interrupt time. 

7 YieldFlag:BYTE 

Indicator for performing yields. Valid only at task time. 

8 TCYieldFlag:BYTE 

Indicator for performing time-critical yields. Valid only at task 
time. 

9 Reserved 

10 Reserved 

1 1 DOS mode Code Page Tag Pointer: DWORD Segment/offset of 
the current code page tag of DOS mode. Valid only at task 
time. 

These variables are maintained by the kernel for the benefit of device 
drivers. 

The returned pointer is a bimodal pointer, that is, the returned 
address is valid in either the DOS mode or the OS/2 mode. Note that 
the address returned is the "address" of the indicated variable; the 
variable may contain a vector to some facility or it may contain some 
structure. 
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Purpose 

This routine is used to obtain a Logical ID (LID) for devices that exist 
(that is, devices that are "awake"). 

Processing 



; 0 = all otiier LIDs 
; 1 = DMA. POS 

MOV DL,DevHlp_GetLIDEntry 
CALL [Device_Help] 

Results 

'C Clear if no error 

AX = LID number 
'C Set if error 

AX = error code 



Remarks 

GetLIDEntry is used by a device driver to obtain a LID entry. Because 
OS/2 does not support the Advanced BIOS Sleep/Wake functions, only 
devices that are ''awake'' are considered to exist and thus available to 
device drivers. 

This function may be employed in two ways. One way is for the 
device driver to specify a relative LID. Because the ordering of LIDs 
corresponds to ordering of the physical devices, a device driver that 
desires to support a certain relative device can determine if a LID 
entry is available. (An example is a character device driver that sup- 



MOV AL.DevicelD 
MOV BL.RelativeLID# 



Desired Device ID 

Nth Logical ID of this Device ID 
(0 - FF) where 0 = first unclaimed 
LID (i.e., first one available) 
1 = the first LID 

Requested LID indicator 



MOV DH.DeviceState 



LID already owned. 

LID does not exist 
ABIOS not present. 
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ports COM4; that is, it wishes to get the LID entry for the fourth COM 
port.) 

The other way to use this function is for the device driver to request 
the first available LID for its device type. (An example is a block 
device driver that wishes to get the first available LID for diskettes.) 

In either use of this function, GetLIDEntry will search the ABIOS 
Common Data Area table for an entry corresponding to the specified 
Device ID. If an entry is located that matches the caller's form of 
request, it is returned to the caller. If a LID entry is found but already 
owned, an error is returned. If no LID entry is fpund, an error is also 
returned. 

Some LIDs will not be allocated to device drivers. Certain Device IDs 
are used by the operating system kernel to perform such actions as 
mode switching. The reserved Device IDs are: 

• System Services 

Certain LIDs will be allocated as shared. For these Device IDs, 
GetLIDEntry will allow multiple device drivers to access the LID con- 
currently. It is up to the device driver to determine if the device is 
busy or available for use when needed. The list of Device IDs that 
are allocated as shared follows: 

• DMA 

• POS 

Note: GetLIDEntry must be called with the DeviceState parameter set 
to 1 in order to obtain a LID for these Device IDs. |n all other cases, 
DeviceState must be set to 0. 

Note: DS must point to the device driver's data segment. If DS was 
previously used In a PhysToVirt calj, it must be reset to the device 
driver's data segment. 
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Memory Segment 



Purpose 

Lock is called by device drivers at task time to lock a memory 
segment. 

Processing 

MOV AX,segment_@ 
MOV BH, duration 

MOV BL.waitflag 

MOV DL,DevHlp_Loclc 
CALL [Device_Help] 

Results 

'C Clear if segment locked 

AX:BX = lock handle 
'C Set if segment unavailable or invalid handle. 

AX, BX not preserved 

Remarks 

If Xhe segment is unavailable, the caller must specify v^hether Lock 
should block until the segment Is available and locked, or return 
immediately. 

If the advisory lock duration parameter indicates that the segment is 
expected to be locked (fixed) for a long time, the segment may be 
moved to the region reserved for fixed, OS/2 mode segments. 

The duration of the lock must be set to SHORT-TERM for operations 
that are expected to complete in two seconds or less. Use of short- 
term locks for longer periods of time prevents an adequate amount of 
movable, swappabie memory from being available for system use. 



Selector or segment 
Advisory duration of lock 

= 0 if short-term 

= 1 if long-term 
;= 0 Block till locked 
= 1 Return if it is not 
immediately available 
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Prior to requesting a lock on a process-supplied address, a device 
driver must verify the process' access to the memory with the DevHIp 
VerifyAccess. The device must not yield the CPU between the 
VerifyAccess and the Locl<, otherwise the process could shrinl< the 
segment before it has been locked. Once the user access has been 
verified, the device driver may lock the segment (and convert the 
address to a 32-bit physical address). The access verification is valid 
for the duration of the lock. 

The Lock call need only be done on addresses that are received from 
user processes (such as an address that is passed via an lOCti). 
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Purpose 

MonFlush removes all data from the specified monitor chain (such as 
the data stream). 

Processing 

MOV AX,monitor_handle ;MonitorCreate handle for chain 

MOV DL,DevHlp_MonFlush 
CALL [Device.Help] 

Results 

'C Clear if OK 

AX = 0 
•C Set if error 

AX = error code 

Invalid monitor handle 

Remarks 

This function may be called at task time in the OS/2 mode only. 

The general format of monitor records requires that every record 
contain a flag word as the first entry. One of the flags is used to indi- 
cate that this record is a flush record. The flush record consists of 
only the flag word. This record is used by monitors along the chain to 
reset internal state information and to assure that all internal buffers 
are flushed. The flush record must be passed along to the next 
monitor because the monitor dispatcher will not process any more 
information until the flush record is received at the end of the chain. 

Subsequent MonWrite requests will fail (or block) until the flush com- 
pletes. 

The state of the interrupt flag is not preserved across calls to this 
DevHIp. 
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Purpose 

MonitorCreate creates an initially empty chain of monitors or 
removes an empty chain of monitors. 



Processing 

LES SI,final_buffer 



LDS 
MOV 



MOV 



; Address of device driver's 

; monitor chain buffer 
DI,notify_rtn ;Address of notification routine 

AX, Handle ; Handle for this chain 

= 0 create new monitor chain 
< > 0 specifies chain to be removed 

(returned from previous create call) 

DL , DevHl p_Moni torCreate 



CALL [Device^Help] 



Results 

'C Clear if OK 

AX = monitor chain handle if Handle was "0". 
AX = G if handle was not "0". 
'C Set if error 
AX = error code 

Invalid monitor handle 
Not enough memory 
Monitor chain not empty 
Invalid parameter 
(If handle not 0, this error is returned if 
all monitor tasks registered with this chain 
have been previously deregistered.) 



Remarks 

The monitor chain buffer is a buffer owned by the device driver. On 
calling MonitorCreate, the first word of this buffer is the length of the 
buffer in bytes (including the first word). 

When the monitor chain handle specified is 0, a new monitor chain is 
created. When the monitor chain handle specified is not 0, the 
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monitor chain created by a previous MonitorCreate call is removed, 
or destroyed. 

A monitor chain is a list of monitors, with a device driver monitor 
chain buffer address and code address as the last element on this 
list. Data is placed into a monitor chain via the MonWrite function; 
the monitor dispatcher feeds the data through all registered monitors, 
putting the resulting data, if any, into the specified device driver 
monitor chain buffer. When data is placed in this buffer the device 
driver's notification routine is called at task time. The device driver 
should initiate any necessary action in a timely fashion and return 
from the notification entry point without delay. 

Note: If the MonWrite function is called at interrupt time and if the 
monitor chain is empty, the driver notification routine will be called at 
interrupt time. Under all other circumstances it is called at task time. 

The MonitorCreate function establishes one of these monitor chains. 
The chains are created empty so that data written into them is placed 
immediately into the device driver's buffer. 

This routine can also destroy a monitor chain If the handle parameter 
(AX) is non-zero. The non-zero value is the handle of the chain to 
remove. 

This function may only be called at task time in the OS/2 mode. 

A MonitorCreate call must be made before a monitor can be Regis- 
tered with the chain. This can be done at any time including during 
the installation of the device driver at system initialization. 

Notification Routine Considerations 

• The notification routine (notify_rtn) is called by the monitor dis- 
patcher when a data record has been placed in the device driv- 
er's monitor chain buffer. The monitor dispatcher sets ES:SI = 
address of the device driver's monitor chain buffer and DS = the 
device driver's DS before calling the notification routine. 

• The device driver must process the contents of the monitor chain 
buffer before returning to the monitor dispatcher. This entry point 
will be called in the OS/2 mode only. 
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• When the notify_rtn is called, the first word of the buffer is filled in 
with the length of the record just sent to the device driver. There 
is one notification routine call per record. 
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Purpose 

MonWrite passes data records to the monitors for filtering. 
Processing 

LDS SI,data_record_offset ; Offset of data record in DS 
MOV CX, count ;Byte count of data record 

MOV AX,monitor_handle ; handle for chain returned from 

; previous MonitorCreate call 
MOV DH,wait_flag ;wait/nowait flag 

MOV DL,DevHlp_MonWrite 
CALL [Device_Help] 

Results 

'C Clear if OK 

AX = 0 
'C Set if error 
AX = error code 

Invalid monitor handle 
Not enough memory 
Data record too large 

Remarks 

This function may be called at task time or interrupt time. The 
wait_flag is set to 0 if the MonWrite request occurs at task or user 
time and the device driver wishes to have the monitor dispatcher 
perform the synchronization. A value of 1 is specified if no wait is 
required. A value of 1 must be specified at Interrupt time. 

The DS register must be set to the device driver data segment. 
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The not-enough-memory condition can arise when the MonWrite call 
is made and the buffer does not contain sufficient free space to 
receive the data. If this condition occurs at interrupt time, an overrun 
has occurred. If it occurs at task (or user) time, the process can 
block. 

A MonFlush in-progress can also cause a not-enough-memory condi- 
tion. 

Each call to MonWrite will send a single complete record. The data 
sent by this call is considered to be a whole record. A data record 
must not be larger than the length of the device driver's monitor 
chain buffer minus two bytes. 

The st^te of the interrupt flag is not preserved across calls to this 
DevHIp. 
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Purpose 

This function converts a 32-bit address to a GDT selector-offset pair. 
Processing 

MOV AX,address_high ;32-bit physical address 

MOV BX.addressJow ; 

MOV CX, length ; Length of segment 

MOV SI, selector ; Selector to be setup 

MOV DL.DevHlp_PhysToGDTSelector 

CALL [Device_Help] 

Results 

'C Cleared if successful 
'C Set if error 
AX = error code 

Invalid address 

Invalid selector 

Remarks 

PliysToGDTSelector is used to provide addressability through a GDT 
selector to data. A bimodal device driver supports both real mode 
and protect mode I/O and must be able to transfer data without being 
dependent on the current mode of operations. In addition, the inter- 
rupt handler of a bimodal device driver must be able to address data 
buffers regardless of the context of the current process (the current 
LDT will not necessarily address the data space that contains the 
data buffer that the interrupt handler needs to access). The GDT 
selector's addressability will remain valid and the same until another 
PhysToGDTSelector call is made for the same selector. 

The AltocGDTSelector function is used at INIT time to allocate the 
GDT selectors that the device driver may use with the 
PhysToGDTSelector. The RealToProt function (see "RealToProt 
Change Mode from Real to Protect Mode" on page 8-58) is used to 
change processor mode from real mode to protect mode, and the 
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ProtToReal function (see "ProtToReal Change Mode from Protect to 
Real Mode" on page 8-49) is used to return tlie processor to real 
mode. The device driver must always return the processor to the 
same mode it was in when entered if either the ProtToReal or 
RealToProt functions are used. 

PhysToGDTSelector creates selector:offset addressability for a 32-bit 
physical address. The selector created, however, does not represent 
a normal memory segment such as those usually managed by OS/2 
and is more of a "fabricated segment" for private use by the device 
driver. Such a segment can not be passed on system calls and may 
only be used by the device driver to fetch data. 
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Purpose 

In the OS/2 mode PhysToUVirt converts a 32-bit physical address to a 
valid selector-offset pair addressable out of the current LDT. In the 
DOS mode, PhysToUVirt converts a 32-blt physical address to a valid 
segment-offset pair, if the address is below 1 megabyte. 

Processing 

MOV AX,address_high ;32-bit physical address 

;(or selector, if request type 2) 
MOV BX.addressJow ; 

MOV CX, length ; Length of area (less than or 

; equal to 65535, 0 = 65536) 

MOV DH,request_type ;Type of Request 

; 0 - get virtual address, make 
; segment readable/executable 
; 1 - get virtual address, make 
; segment readable/writable 
; 2 - free virtual address 
; (OS/2 mode only) 

MOV DL,DevHlp_PhysToUVirt 

CALL [Device.Help] 

Results 

'C Set if error 

Invalid address 
'C Cleared if successful 

ES:BX — segment/selector-offset pair 
(for request types 0 and 1). 

Remarks 

PhysToUVirt will leave its result in ES:BX. PhysToUVirt can also be 
used in the OS/2 mode to free a selector returned on a prior 
PhysToUVirt call. 

This function Is typically used to provide a caller of a device driver 
with addressability to a fixed memory area, like ROM code and data. 
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The device driver must know the physical address of the memory 
area to be addressed. 

In the OS/2 mode, the offset returned in BX is 0 for request types 0 
and 1. 

For request type 2, AX contains a selector on entry to PhysToUVirt, 
and BX and CX are ignored. 

PhysToUVirt creates selector:offset LDT addressability for a 32-bit 
physical address. This function is provided so a device driver can 
give an application process addressability to a fixed memory area, 
such as in the BIOS-reserved range from 640Kb to 1Mb. It can also 
be used to give a client application addressability to a device driver's 
data segment. 

The selector created, however, does not represent a normal memory 
segment such as those usually managed by OS/2 and is more of a 
fabricated segment for private use between a device driver and an 
application. Data within such a segment cannot be passed on system 
calls and may only be used by the receiving application to fetch data 
variables. 
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Purpose 

In the OS/2 mode, PhysToVirt converts a 32-bit address to a valid 
selector-offset pair. In the DOS mode, PhysToVirt converts a 32-bit 
address to a segment-offset pair. 

Processing 

MOV AX,address_high ;32-bit physical address 

MOV BX.addressJow 

MOV CX, length '.Length of segment 

MOV DH, result ; Leave result 

; 0 in DS:SI 

: 1 in ES:OI 

MOV DL,DevHlp_PhysToVirt 
CALL tDevice_Help] 



Results 

'C Cleared if successful 
'C Set if error 

AX = Error code 
DH Set to 0 on input 

OS: SI Valid virtual address 

ES No mode switch, ES is preserved. 

Mode switch, if ES contains the address of the 
device driver data segment on input, it will 
be converted to a valid virtual address. 
Otherwise, it is set to zero. 
DH Set to 1 on input 

ES:DI Valid virtual address 

DS No mode switch, DS is preserved. 

Mode switch, if DS contains the address of the 
device driver data segment on input, it will 
be converted to a valid virtual address. 
Otherwise, it is set to zero. 
'Z' Cleared if no change in addressing mode 
'2' Set if addressing mode has changed 
previously stored addresses 
must b6 recalculated. 
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Remarks 

PhysToVirt will leave its result in either ES.DI or DS.SI, giving the 
device driver the ability to move strings in either direction. The 
returned virtual address will not remain valid if the device driver 
blocks or yields control. The returned virtual address also may be 
destroyed if the device driver routine which issues the PhysToVirt 
calls another routine. 

On the Personal Computer AT and Personal Computer XT Model 286, 
If the current mode is the DOS mode and the data lies above 1 Mb, 
then PhysToVirt will set the target segment register (DS or ES) with a 
special value and return to the device driver with interrupts disabled. 
An UnPhysToVirt DevHIp call must be made prior to exiting the 
device driver in this case. 

The device driver must not enable interrupts or change the segment 
register (ES or DS - whichever contains the returned value) before the 
device driver has finished accessing the data area. Any change to 
the contents of the segment register in question will invalidate the 
mapping. For example, saving and restoring the value in the 
segment register will cause the register to refer to memory in the first 
megabyte of system memory. Once the device driver has finished 
accessing the data area, it must restore the previous interrupt state. 

While pointer(s) generated by this routine are in use, the device 
driver may only call another PhysToVirt request. No other DevHIp 
routines can be called, because they may not preserve the special 
DS/ES values created by the PhysToVirt. 

The performance characteristics of PhysToVirt are highly variable. In 
the DOS mode where the entire data area lies below 1 MB or in the 
OS/2 mode, PhysToVirt is very fast. In the DOS mode where part or 
all of the data area lies above 1 Mb, PhysToVirt will be very slow. 

On the PS/2, if the current mode is the DOS mode and the data lies 
above 1 Mb, then PhysToVirt will switch into the OS/2 mode and 
return a selector-offset pair. This mode switch requires the use of the 
companion function, UnPhysToVirt, to switch back to the DOS mode. 
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UnPhysToVirt is required to be used any time PhysToVirt is used, with 
certain qualifications: 

1. When use of the converted addresses Is ended (no more 
PhysToVlrts), and 

2. Before the procedure which Issued the PhysToVirt returns to Its 
caller. 

In addition, multiple PhysToVirt calls may be performed prior to 
Issuing the UnPhysToVirt. Only one call to UnPhysToVirt is needed. 
When calling PhysToVirt the first time, DS must point to the device 
driver's device header. 

PhysToVirt preserves the registers CS, SS, SP, and DS If called with 
DH = 1, or ES If called with DH=0. The only exception to this case is 
when a mode switch takes place. If a switch to the OS/2 mode occurs 
because the specified address lies above 1 Mb and the current mode 
was the DOS mode, then: 

• The segment addresses In CS and SS will be set for the current 
mode. 

• SP will be preserved. 

• DS will be preserved unless It Is being used for the converted 
address. 

• ES will be set for the current mode only If It contains the data 
segment value of the device driver and Is not being used for the 
converted address. 

If that a previous PhysToVirt had been done (using either DS or ES) 
with no address mode change flagged, then the PhysToVirt that 
requires a mode switch to the OS/2 mode causes the previously con- 
verted PhysToVirt address to be invalid for the current mode. 
PhysToVirt must be re-Issued to recalculate the address. 

When PhysToVirt is being used to recalculate an address after a 
mode switch is flagged, the second PhysToVirt will not cause a mode 
switch. The previous address will therefore be valid and preserved 
(so long as the recalculation uses the opposite segment register as 
the one that originally caused the mode switch). 
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Note also that in the event of a mode switch, any previously stored 
address pointers that contain the DS for the device driver's data 
segment must be stored again by the device driver. The zero flag 
(ZF) is set if a change in address mode occurred. In this case the 
device driver must recalculate and store again any buffer addresses 
that were previously saved. 

The pool of temporary selectors used by PhysToVirt in the OS/2 mode 
Is not dynamically extendable. The converted addresses are valid as 
long as the device driver does not relinquish control (Blocic, Yield, or 
RET). An interrupt handler may use converted addresses prior to its 
EOl, with interrupts enabled, interrupt handlers should issue an 
UnPhysToVirt if necessary before mal<ing the EOl statement. If an 
interrupt handler needs to use converted addresses after its EOl, it 
must protect the converted addresses by running with interrupts disa- 
bled. 

Note that the task-time strategy routine of a device driver may run 
enabled on a PS/2. 

The segment length parameter must be set to the length of the 
transfer. 

Note: For performance reasons, a device driver should try to opti- 
mize its usage of PhysToVirt and UnPhysToVirt. For the first 
PhysToVirt call that the device driver makes, it should pick the 
address that is likely to cause a mode switch and use the ES register. 
This would permit the mode switch to take place and retain the driv- 
er's data segment (DS). 

For examples on how to use PhysToVirt, see the examples discussed 
in the section "Using PhysToVirt and UnPhysToVirt" on page 7-68. 
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Purpose 

This DevHIp allows a device driver to change processor mode from 
protect mode to real mode at interrupt time. 

Processing 

MOV DL.DevHlp_ProtToReal 
CALL [Device.Help] 

Results 

'C Cleared if successful 

Mode has changed to real mode. 
'C Set if error 

Mode has not been changed. 

Remarks 

On entry, DS should be set to the device driver's data segment. On 
exit, the contents of ES have been changed. 

This function is used at interrupt-time to change the processor mode 
from protect mode to real mode In order to service the device inter- 
rupt. The function DevHlp_RealToProt is used to switch the processor 
mode bacl< from real mode to protect mode (see "RealToProt Change 
Mode from Real to Protect Mode" on page 8-58). 

Once the processing is complete, the device driver must return the 
processor to the original mode the processor was in when the device 
driver was entered. For example: 
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Device driver entered in Protect Mode. 

Call DevHl p_ProtToReal - change to real mode. 

Device processing in Real Mode 

Call DevHl p_Real ToProt - change back to protect mode. 
Device driver returns or exits. 

The following shows an example of how to determine whether the 
processor must be switched from protect mode to real mode and back 
by checking the MSW: 



rcr ax.l 

jnc rml 

DevHl p ProtToReal 



smsw ax 
push ax 



get current msw 
save original msw 
pe bit -> cf 

already real mode? 

no, switch to real mode 



rml: 



process in real mode 



pop ax 
rcr ax,l 
jnc rm2 
DevHl p Real ToProt 



get original msw 

pe bit -> cf 

originally in real mode? 

no, switch back to protect mode 



rm2; 
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Purpose 

PullParticular pulls the specified packet from the selected request 
packet linked list. If the packet is not found, then an indicator is set 
on return. 

Processing 

MOV SI, OFFSET DS: queue 

LES BX,request_packet 
MOV DL,DevH1p_Pull Particular 
CALL [Device_Help] 

Results 

'C Cleared if no error. 
'C Set if the specified request is not found. 

Remarics 

A device driver uses PushReqPacket/PullReqPacket to maintain a 
work queue for each of its devices. PullParticular is used to remove 
a specific request packet from the work queue, typically for the case 
where a process has terminated before finishing its I/O. 

PullParticular may also be used to remove request packets that were 
allocated by an AllocReqPacket from the request packet linked list. 



: Location of queue head (should 
; match PushRequest value) 
; Pointer to request packet. 
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Purpose 

PullReqPacket pulls the next waiting request packet from the 
selected request packet linked list. If there is no packet in the list, 
then an indicator Is set on return. 

Processing 

MOV SI, OFFSET DS: queue ; Location of queue head (should 

; match PushReqPacket value) 

MOV DL,DevHlp_PunReqPacket 
CALL [Device_He1p] 

Results 

'C Set if there is no request. 
'C Cleared if no error. 

ES:BX Pointer to request packet. 

Remarks 

A device driver uses PushReqPacket/PullReqPacket to maintain a 
work queue for each of its devices/units. The device driver must 
provide the storage for the DWORD work queue head, which defines 
the start of the request packet linked list. The work queue head must 
be initialized to 0. 

PullReqPacket may also be used to remove request packets that were 
allocated by an AllocReqPacket from the request packet queue. 
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Purpose 

PushReqPacket adds the current device request packet to the linked 
list of packets to be executed by the device driver. 

Processing 

MOV SI, OFFSET DS:queue 

LES BX,request_pacl(et 

MOV DL,DevHlp_PushReqPacket 
CALL [Device.Help] 

Results 

None 

Remarks 

A device driver uses PushReqPacket/PullReqPacket to maintain a 
work queue for each of its devices. The device driver must provide 
the storage for the DWORD work queue head, which defines the start 
of the request packet linked list. The work queue head must be ini- 
tialized to 0. 

The device driver task-time thread should add all incoming read/write 
requests to its request list. The driver task-time thread should then 
determine whether the interrupt-time thread is active, and if not, it 
should send the request to the device. Because the device may be 
active at this point, the driver task-time thread must turn off interrupts 
before calling the device; otherwise a window exists in which the 
device finishes before the packet is put on the list. 

PushReqPacket may also be used to place request packets that were 
allocated by an AllocReqPacket In the request packet work queue. 



•.Location of the DWORD queue head 
; (which points to the first 
; request in the list.) 
; Pointer to request 
; packet. 
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Purpose 

QueueFlush clears the character queue structure that is specified (it 
empties the buffer). 

Processing 

MOV BX, OFFSET OS: queue 

MOV DL,DevHlp_QueueFlush 
CALL [Device_Help] 

Results 

None 

Remarks 

QueueFlush operates on the simple character queue structure initial- 
ized by Queuelnit. 



; Points to the queue structure 
; to be flushed. (The Qsize 
; field must be set up.) 
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Purpose 

Queuelnit initializes the specified character queue structure. 



Processing 

MOV BX, OFFSET DS: queue ; Points to the queue structure 

; to be initialized. (The 
; Qsize field must be set up.) 

MOV DL,DevHlp_QueueInit 
CALL [Device.Help] 



Results 



None 



Remarks 



Queuelnit must be called before any other queue manipulation sub- 
routine. 



Prior to this call, the device driver must allocate the character queue 
buffer with the following queue header and initialize the Qsize field. 



For example: 



Qsize DW ? 

Qchrout DW ? 

Qcount DW ? 

Qbase DB ? 



;size of queue in bytes 
; index of next char out 
: count of chars in the queue 
; start of queue buffer 
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QueueRead 

Read a Character From a Queue 



Purpose 

QueueRead returns and removes a character from the beginning of 
the specified character queue structure. If the queue is empty, an 
indicator is set. 

Processing 

MOV BX, OFFSET DSrqueue ;Points to the queue structure. 
MOV DL , DevHl p_QueueRead 
CALL [Device_Help] 

Results 

'C Set if the queiie is empty, 

'C Cleared otherwise. 

AL The character read from the queue. 

Remarks 

QueueRead operates on the simple character queue structure initial- 
ized by Queuelnit. 
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Queue Write 
Put Character into Queue 



Purpose 

QueueWrite adds a character at the end of the specified character 
queue structure. If the queue is full, an indicator is set. 

Processing 

MOV BX, OFFSET DS: queue ; Points to the queue structure. 
MOV AL.char ; Character to insert at the end 

; of the queue. 

MOV DL,DevHlp_QueueWrite 
CALL [Device_Help] 

Results 

'C Clear if character stored successfully. 
'C Set if queue is full. 

Remarks 

QueueWrite operates on the simple character queue structure initial- 
ized by Queuelnit. 
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RealToProt 

Change Mode from Real to Protect Mode 



Purpose 

This DevHIp allows a device driver to change processor mode from 
real mode to protect mode at interrupt time. 

Processing 

MOV DL.DevHlp_RealToProt 
CALL [Device_Help] 

Results 

'C Cleared if successful 

Mode has changed to protect mode. 
'C Set if error 

Mode has not been changed. 

Remarks 

On entry, DS should be set to the device driver^s data segment. On 
exit, the contents of ES have been changed. 

This function is used at interrupt-time to change the processor mode 
from real mode to protect mode in order to process the device inter- 
rupt. The function DevHlp_ProtToReal is used to switch the processor 
mode back from protect mode to real mode (see "ProtToReal Change 
Mode from Protect to Real Mode" on page 8-49). 

Once the processing is complete, the device driver must return the 
processor to the original mode that the processor was in when the 
device driver was entered. For example: 
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RealToProt 

Change Mode from Real to Protect Mode 



Device driver entered in Real Mode. 

Call DevHlp_RealToProt - change to protect mode. 



Device processing in Protect Mode 



Call DevH1p_ProtToRea1 - change back to real mode. 
Device driver returns or exits. 

The following shows an exannple of how to determine whether the 
processor must be switched from real mode to protect mode and back 
by checking the MSW: 

smsw ax ; get current msw 

push ax : save original msw 

rcr ax.l ; pe bit -> cf 

jc pml ; already protect mode? 

DevHlp RealToProt ; no, switch to protect mode 



pml: . 



: process in protect mode 



rcr 
jc 

DevHlp 



pop 



ax ; get original msw 

ax.l ; pe bit -> cf 

pm2 ; originally in protect mode? 

ProtToReal ; no, switch back to real mode 



pm2: . 
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Register 
Add Monitor 



Purpose 

Register adds a monitor to the chain of monitors for a class of device. 



Processing 

LES SI,input_buffer ;Acldress of input buffer 

MOV DI,output_buffer_offset ;Offset of output buffer 

MOV CX,monitor_PID ; Process ID of monitor task 

MOV AX,monitor_hanclle ; handle for chain returned from 

; previous MonitorCreate caT 

MOV DH,placement_flag ;High or Low place in chain 
MOV DL,DevHlp_Register 
CALL [Device_Help] 



Results 

'C Clear no error 
'C Set if error 
AX = error code 

Invalid monitor handle 
Not enough memory 



Remarlcs 

This function may only be called at task time in the OS/2 mode. 

A monitor chain must have previously been created with 
MonitorCreate. 

A single process may register more than one monitor (with 
"different" input and output buffers) with the same monitor chain. 

The first word of each of the input and output buffers must contain the 
length in bytes (length word inclusive) of the buffers. The length of 
the monitor's input and output buffers must be greater than the length 
of the device driver's buffer plus 20 bytes. 
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Register 
Add Monitor 



The input buffer, output buffer offset, and placement flag are supplied 
to the device driver by the monitor task (which Is asking to be regis- 
tered). 

The device driver must identify the monitor chain with the monitor 
handle returned from a previous MonitorCreate call. The device 
driver can determine the PID of the requesting monitor task from the 
Local InfoSeg. Refer to "GetDOSVar Get Address of Important DOS 
Variables" on page 8-29. 
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ResetTimer 

Reset Timer Handler 



Purpose 

ResetTimer removes a timer handler for the device driver. 
Processing 

MOV AX, Offset cs:timer_liandler ;offset to timer liandler 

MOV DL,DevH1p_ResetTimer 
CALL [Device_Help] 

Results 

'C Cleared if no error 
'C Set if error 
Invalid handler 

Remarks 

This function removes a timer handler from the list of timer handlers. 
Timer handlers are analogous to the user timer interrupt (Int 1CH). 
Refer to "Ticl<Count Modify timer" on page 8-84 for a discussion on 
timer handlers. 

DS should be set to the device driver's data segment, if the device 
driver had done a PhysToVirt referencing the DS register, it should 
restore DS to the original value. 
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ROMCritSection 
Flag Critical Section off Execution 



Purpose 

ROMCritSection flags a critical section of execution in a DOS mode 
software interrupt handler to prevent the DOS mode from being sus- 
pended in the baclcg round. 



Processing 

MOV AL,enter_or_exit 



MOV DL,DevHlp_ROMCritSection 
CALL [Device_Help] 



Critical Section flag 
=0 exit 
< > 0 enter 



Results 

None. 



Remarks 

This service is called by a device driver's DOS mode software inter- 
rupt handler. 

Sections of ROM BIOS code must be protected from preemption. Pre- 
emption occurs when a user switches away from the DOS mode. This 
causes the DOS mode to be suspended in background. However, 
some I/O processing cannot tolerate being suspended. Specific 
examples are the printer (BIOS INT 17H), disk (BIOS INT 13H), and 
screen (BIOS INT 1 0H). It is the responsibility of the OS/2 device 
driver to intercept the appropriate ROM BIOS interrupt and issue the 
DevHIp function call, ROMCritSection. to protect the ROM BIOS crit- 
ical section of execution. 
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ROMCritSection 

Flag Critical Section of Execution 



Note: When the OS/2 device driver issues ROMCritSection to "enter" 
a ROM BIOS critical section, the user will not be able to switch away 
from the screen of the DOS mode to another screen. This has poten- 
tial problems for the user. For example, if some DOS mode 
terminate-and-stay-resldent program takes control while the CPU is 
executing the ROM BIOS, the time spent in the ROM BIOS critical 
section will be longer, and the user will be unable to switch tasks. 
The worst case is that the terminate-and-stay-resident application is 
Interactive, never allowing the OS/2 device driver to Issue the "exit" 
from critical section and never allowing the user to switch away from 
the screen of the DOS mode until the user terminates the application. 
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Run 

Release Blocked Thi^ad 



Purpose 

This is the companion routine to Block. When Run is called, it 
awakens all threads that were blocked for this particular event identi- 
fier. 

Processing 

MOV BX,event_id_low ;Low word of event identifier. 

MOV AX,event_id_high ;High word of event identifier. 

MOV DL,DevH1p_Run 
CALL [Device.Help] 

Results 

AX = count of those woken. 
'Z' set according to AX. 

Remarks 

Run returns immediately to its caller; the awakened threads will be 
run at the next available opportunity. Run is often called at interrupt 
time. 

Refer to "Block This Thread From Running" on page 8-19 for a 
detailed discussion. 
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SchedClockAddr 

Get system clock routine 



Purpose 

This service Is provided to the clock device driver to allow it to obtain 
a pointer to the address of the system's clock tick handler, 
SchedClock. SchedClock must be called on each occurrence of a 
periodic clock tick. 

Processing 

MOV AX,Pointer_Save 

MOV DL,DevHlp_ScliedClockAddr 
CALL [Device_Help] 

Results 

Pointer_Save will contain the address of 
the system tick handler. 

Remarks 

The clock device driver calls this DevHIp service during the clock 
device driver's initialization. For input to this DevHIp, the clock 
device driver must ensure that its DS points to the device driver's 
data segment and supply the offset to a DWORD area. The DevHIp 
service will then fill in the device driver's save area with a bimodal 
pointer to a DWORD in system memory. The DWORD in system 
memory contains the pointer to the SchedClock routine. This is illus- 
trated in the following diagram: 

Device driver 
data segment 



Pointer.Save 


System 
ScliedClock 
pointer 


System 
timer 
handier 


pointer 




SchedClock.Addr 




ScliedClocl( 
routine 











; Offset in DS to a DWORD 
; where the pointer will 
; be returned 
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SchedClockAddr 
Get system clock routine 



The pointer that is returned to the device driver in Pointer_Save is a 
bimodal pointer which is valid in either the DOS mode or the OS/2 
mode. The device driver does not need to perform any conversions 
on this pointer for DOS mode or OS/2 mode operations. The device 
driver can then use the pointer it has in Pointer_Save to call 
SchedClock. SchedClock is called by the clock device driver with a 
CALL FAR INDIRECT, using the pointer to the area which contains the 
actual address of the SchedClock routine. 



SchedClock must be called at Interrupt time for each periodic clock 
tick to indicate the passage of system time. The Tick'' is then dis- 
persed to the appropriate components of the system. A definition of 
the interface to SchedClock follows. 



MOV AL.millisecs 
MOV DH.EOIflag 



CALL [pointer] 



Milliseconds since last call 
Indicator of EOI 

= 0 prior to EOI 

= 1 after EOI 
Pointer to the area which 

contains the actual address 

of SchedClock 



The clock device driver's interrupt handler must run with interrupts 
enabled as the convention, prior to issuing the EOI for the timer inter- 
rupt. Any critical processing, such as updating the fraction-of- 
seconds count, must be done prior to calling SchedClock. 
SchedClock must then be called to allow system processing prior to 
the dismissal of the interrupt. When SchedClock returns, the clock 
device driver must issue the EOI and call SchedClock again. Note 
that once the EOI has been issued, the device driver's interrupt 
handler may be reentered. The DevHIp SchedClock Is also reentrant. 

The device driver must not get the actual address of the SchedClock 
routine but instead use the pointer returned by the DevHIp call. 
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SemClear 

Release a Semaphore 



Purpose 

This function releases a semapliore and restarts any blocked threads 
waiting on the semaphore. 

Processing 

MOV BX , sem_handl e_l ow 
MOV AX,sem_handle_high 
MOV DL,DevHlp_SemClear 
CALL [Device_Help] 

Results 

'C Cleared if no error 
'C Set if error 
AX = error code 

errorjnvalid _handle 

error_excl_sem_al ready_owned 

error_i nval i d_at_i nterrupt_time 

error_protecti on_vi ol ati on 

Remarks 

A device driver may clear either a RAM semaphore or a system 
semaphore. The device driver may obtain (own) a semaphore 
through SemRequest. 

The semaphore handle for a RAM semaphore is the virtual address of 
the doubleword of storage allocated for the semaphore. Virtual 
address is used as a generic term for addresses: segment:offset for 
the DOS mode; selector:offset for the OS/2 mode. To access a RAM 
semaphore at interrupt time, the device driver must locate the 
semaphore In the device driver's data segment (DS). 

For a system semaphore, the handle must be passed to the device 
driver by the caller by way of a generic lOCtl. The device driver must 
convert the caller's handle to a system handle with SemHandie. 



: Semaphore handle 
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SemClear 
Release a Semaphore 

A RAM semaphore can be cleared at interrupt time only if it is in 
storage tiiat is directly addressable by the device driver, that is, in 
the device driver's data segment. 
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SemHandle 

Obtain a Semaphore Handle 



Purpose 

This function provides a semapliore handle to the device driver. 
Processing 

MOV BX,sem_l(ey_low ; Semaphore identifier 

MOV AX,sein_key_high ; 

MOV DH,usage_flag ; Indicates if in use 

; = 0 not-in-use 

; = 1 in-use 
MOV DL.DevHlp_SemHandle 
CALL [Device_Help] 

Results 

'C Cleared if no error 

AX:BX set to the system handle. 
'C Set if error 

AX contains error code. 

Invalid handle for the semaphore if DH - 1. 

Remarlcs 

This function is used to convert the semaphore handle (or user "key") 
provided by the caller of the device driver to a system handle that the 
device driver may use. This handle then becomes the "key" that the 
device driver uses to reference the System Semaphore. This allows 
the System Semaphore to be referenced at interrupt time by the 
device driver. This "key" is also used when the device driver is fin- 
ished with the system semaphore. The device driver must call 
SemHandle with the usagejiag indicating that the device driver is 
finished with the system semaphore. 

SemHandle is called at task time to indicate that the system 
semaphore is IN-USE, and is called at either task time or interrupt 
time to indicate that the system semaphore is NOT-IN-USE. IN-USE 
means that the device driver may be referencing the System 
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SemHandle 
Obtain a Semaphore Handle 



Semaphore. NOT-IN-USE means that the device driver has finished 
using the system semaphore and will not be referencing it again. 

The "key" of a RAM semaphore is its virtual address, where virtual 
address is the generic term for both DOS mode and OS/2 mode 
address forms (segment-offset, selectoroffset). SemHandle may be 
used for RAM semaphores. Because RAM semaphores have no 
system handles, SemHandle will simply return the RAM semaphore 
"key" back to the caller. 

A device driver can determine that a semaphore is a RAM 
semaphore if the key remains unchanged upon return from the 
SemHandle function. If the key returned from SemHandle is different 
than the one passed to the function, then the device driver can deter- 
mine that it is a handle for a System semaphore. 

If carry is returned from this function, the device driver should issue 
the DevHIp Verify Access request with TypeOf Access of Read/Write 
indicated before assuming this Is a RAM semaphore. If a Ram 
semaphore is to be used, it must be accessed only at task time unless 
it is in locked storage. 

It is necessary to call SemHandle at task time to indicate that a 
System Semaphore is IN-USE because: 

1. The caller-supplied semaphore handle refers to task-specific 
system semaphore structures. These structures are not available 
at interrupt time, so SemHandle converts the task-specific handle 
to a system-specific handle. For uniformity, the other semaphore 
DevHIp functions accept only system-specific handles regardless 
of the mode (task time or interrupt time). 

2. An application could delete a system semaphore while the device 
driver Is using it. If a second application were to create a system 
semaphore soon after, the system structure used by the original 
semaphore could be reassigned. A device driver which tried to 
manipulate the original process's semaphore would inadvertently 
manipulate the new process's semaphore. Therefore, the 
SemHandle IN-USE indicator increases a counter so that, 
although the calling thread may still delete its task-specific refer- 
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SemHandle 

Obtain a Semaphore Handle 



ence to the semaphore, the semaphore remains in the system 
structures. 

A device driver must subsequently call SemHandle with NOT-IN-USE 
when the semaphore use is done so that the system senriaphore 
structure can be freed. There must be a call to indicate NOT-IN-USE 
to match every call to indicate IN-USE (one-to-one relationship). 

The state of the interrupt flag is not preserved across calls to this 
DevHIp. 
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SemRequest 
Claim a Semaphore 



Purpose 

This function claims a semaphore. If the semaphore is already 
owned, the thread in the device driver is blocl<ed until the semaphore 
is released or until a timeout occurs. 

Processing 

MOV BX , sem_hancll ej ow 

MOV AX,sem_handle_high 

MOV CX,sem_timeout_low 

MOV DI,seni_timeout_high 



MOV DL , DevHI p_SemRequest 
CALL [Device_Help] 

Results 

'C Cleared if no error. 
'C Set if error. 
AX = error code. 

er ror_s em_t i meout 

error_sem_owner_di ed 

error_i nval i d_handl e 

error_too_many_sem_requests 

error_i nterrupted 

error_protecti on_vi ol ati on 

Remarks 

SemRequest checlcs the state of the semaphore. If it is unowned, 
SemRequest marks it "owned" and returns immediately to the caller. 
If the semaphore is owned, SemRequest will optionally block the 
device driver thread until the semaphore is unowned, then try again. 
The timeout parameter is used to place an upper limit on the amount 
of time to block before returning to the requesting device driver 
thread. 



Semaphore handle 

Timeout value 
in milliseconds 
= -1 wait forever 
= 0 no wait if sem owned 
i > 0 timeout 
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SemRequest 
Claim a Semaphore 



SemClear is used at either tasl^ time or interrupt time to release the 
semaphore. 

The semaphore handle for a RAM semaphore is the virtual address of 
the doubleword of storage allocated for the semaphore. Virtual 
address is used as a generic term for addresses: segmenf.offset for 
the DOS mode; selector:offset for the OS/2 mode. To access a RAM 
semaphore at interrupt time, the device driver must locate the 
semaphore in the device driver's data segment (DS). 

For a system semaphore, the handle must be passed to the device 
driver by the caller through a generic lOCti. The device driver must 
convert the caller's handle to a system handle with SemHandle. 

Note that this service is valid in user mode only for RAM 
semaphores. System semaphores are not available in user mode by 
device drivers. 

The state of the interrupt flag is not preserved across calls to this 
DevHIp. 
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SendEvent 
Indicate an Event 



Purpose 

This routine Is called by a device driver to indicate the occurrence of 
an event. 

Processing 

MOV AH. event 
MOV BX, argument 

MOV DL.DevHlp_SendEvent 
CALL [Device_Help] 

Results 

'C Cleared if no error. 
'C Set if error sending signal. 

Remarks 

The events are defined as: 

• Event = 0 (Reserved) 

• Ctrl + Break 

- event = 1 

- argument = 0 (Reserved) 

• Ctrl + C 

- event = 2 

- argument = 0 (Reserved) 

• Ctrl + NumLock 

- event = 3 

- argument = Foreground session number 



; Event being signalled 
•.Parameter for the event 
: being signalled 
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SendEvent 
Indicate an Event 



• Ctrl + PrtSc 

- event = 4 

- argument = 0 (Reserved) 

• Shift + PrtSc 

- event = 5 

- argument = 0 (Reserved) 

• Session Manager Hot Key from the Keyboard 

- event == 6 

- argument = Hot Key ID 

The keyboard device driver uses the Hot Key ID which was set by 
way of keyboard lOCtI 56H (SET SESSION MANAGER HOT KEY). 
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SetlRQ 

Set Hardware Interrupt Handler 



Purpose 

This service is used to set a hardware interrupt vector to the device 
driver interrupt handier. 

Processing 

MOV AX, Off set CS.-liandler ; Interrupt handler offset 

MOV BX.IRQnum ; Interrupt level number (0 - FH) 

MOV DH,Sliared_Int ; Interrupt sharing (=0 not shared, =1 shared) 

MOV DL,DevHlp_SetIRQ 

CALL [Device_Help] 



Results 

'C Clear if no error 
'C Set if error 

IRQ is not available. 



Remarks 

The attempt to register an interrupt handler for an IRQ to be Shared 
will fail If the IRQ Is already owned by another device driver as Not 
Shared, owned by a DOS mode interrupt handler, or is the IRQ used 
to cascade the slave 8259 interrupt controller (IRQ 2). 

The attempt to register an interrupt handler for an IRQ to be Not 
Shared will fail if the the IRQ is already owned by another device 
driver as Shared or Not Shared, owned by a DOS mode interrupt 
handler, or is the IRQ used to cascade the slave 8259 interrupt con- 
troller. 

DS should be set to the device driver's data segment. If the device 
driver had done a PhysToVirt referencing the DS register, it should 
restore DS to its original value. 

The IRQnum value is range checked and 'C is set if not from 0 to 
OFH. 
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SetROMVector 

Set DOS Mode Software Interrupt Vector 



Purpose 

This service is used to replace a DOS mode software interrupt 
handler with a handier from the device driver. This service returns a 
DOS mode pointer to the previous software interrupt handler for 
chaining. 

Processing 

MOV AX, OFFSET CS: handler 
MOV BX.intnum 
MOV SI, OFFSET CSisaveDS 

MOV DL.DevHlp_SetROMVector 
CALL [Device_Help] 

Results 

'C Clear if no error 

AX:DX = DOS mode pointer to previous header. 

CS:[SI] = DOS mode DS of device driver. 
'C Set if error 

Invalid interrupt number. 

Remarks 

The device driver can register a software interrupt handler for a DOS 
mode software interrupt. This is typically done to intercept a ROM 
BIOS software interrupt, which allows the device driver to perform 
any processing needed to coordinate device I/O between the driver 
and ROM BIOS. 

The device driver may not register a software interrupt handler for 
any of the interrupt vectors reserved for hardware Interrupts. The 
reserved interrupt numbers are: 

08 - OFH 
50 - 57H 
70 - 77H 



; Interrupt handler offset 
; Interrupt number 
; offset in CS of WORD 
; to save DOS mode DS 
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SetROMVector 
Set DOS Mode Software Interrupt Vector 



The device driver's software interrupt handler for the DOS mode soft- 
ware interrupt receives control directly when the interrupt occurs. 
Consequently, the DS register is not set up for the handler on entry. 
The handler must set the DS register with the value that 
SetROMVector had previously saved In the CS:[SI] location. 

When calling SetROMVector, the device driver must ensure that DS is 
set to the device driver's data segment. If the device driver had done 
a PhysToVIrt referencing the DS register, it must restore DS to the 
original value. 
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SetTimer 

Set Timer Handler 



Purpose 

SetTimer adds a timer handler to the list of timer handlers to be 
called on a timer tick. 

Processing 

MOV AX, OFFSET CS:timer_hancner ;Offset of timer jiandler. 

MOV DL,DevHlp_SetTimer~ 
CALL [Device_Help] 

Results 

'C Cleared if no error. 
'C Set if error. 

Timer handler disallowed (maximum number of 
handlers reached or timer handler already set). 

Remarks 

The DevHIp SetTimer is a subset of the DevHIp Ticl^Count. 

This function allows a device driver to add a timer handler to a list of 
timisr handlers called on every timer tick. A device driver may use a 
timer handler to drive a non-interrupt device instead of using time- 
outis with the Block and Run services. Block and Run are costly on 
a character-by-character basis; the cost is one or more task switches 
per character I/O. Timer handlers are required to save and restore 
registers. 

A maximum of 32 different timer handlers are available in the system. 

While a timer handler is in the format of a FAR CALL/RETURN routine 
(when it is finished processing, it performs a return), it operates in 
Interrupt State. The timer handler is analogous to the user timer (Int 
1CH) handler. Care should be taken not to remain in the handler very 
long. 
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Set Timer Handler 



DS should be set to the device driver's data segment. If the device 
driver had done a PhysToVirt referencing the DS register, it should 
restore DS to the original value. 

Timer handlers are responsible for saving and restoring registers on 
entry and exit. 
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SortReqPacket 

Insert Request In Sorted Order To List 



Purpose 

This routine is used by blocl< (disl<) device drivers to add a new 
request to their worl( queue. This routine inserts the request paclcet 
in the linked list of request paclcets in the order of starting sector 
number. 

Processing 

MOV SI, OFFSET DS: queue 



LES BX,request_packet 

MOV DL,DevHlp_SortReqPacl<et 
CALL [Device_Help] 

Results 

None 

Remarks 

The sorting by sector number is aimed at reducing the length and 
number of head seeks. This is a simple algorithm and does not 
account for multiple heads on the media or for target drive in the 
request packet. SortReqPacket inserts the current request packet 
into the specified linked list of packets, sorted by starting sector 
number. 

SortReqPacket may be used to place request packets that were allo- 
cated by an AllocReqPacket in the request packet queue. 



Location to DWORD queue 
head (which points to 
first request). It 
should be initialized 
to 0. 

Pointer to request 
packet. 
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TCYield 
Yield the CPU 



Purpose 

This function is similar to the Yield function, except that the CPU may 
only be yieldeci to a time-critical thread, if one Is available. 

Processing 

MOV DL,DevHlp_TCYield 
CALL [Device_Help] 

Results 

None 

Remarks 

It is not necessary for the device driver to do both a Yield and a 
TCYield; the TCYield function is a subset of the Yield function. 

The one part of the kernel that can take a lot of CPU time is in device 
drivers, particularly those that perform program I/O on long strings of 
data or that poll a device. These device drivers periodically should 
check the TCYield Flag and call the TCYield function to yield the CPU 
to a time-critical thread. 

The location of the TCYield Flag is obtained from the GetDOSVar 
call. 

For performance reasons, the device driver should check the TCYield 
Flag once every 3 milliseconds. If the flag is set, then the device 
driver should call TCYield. 

Because the device driver may relinquish control of the CPU, the 
device driver should not assume that the state of the interrupt flag 
v^ill be preserved across a call to TCYield. 
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TickCount 
Modify timer 



Purpose 

TickCount will register a new timer handler or modify a previously 
registered timer handler to be called on every N timer ticks instead of 
every timer tick. 

Processing 

MOV AX, OFFSET CS:timer_handler 
MOV BX, count 

MOV DL.DevHlp_TickCount 
CALL [Device_Help] 

Results 

'C Cleared if no error 
'C Set if error 

Timer handler cannot be modified or set. 

Remarks 

A device driver may use a timer handler to drive a non-interrupt 
device instead of using timeouts with the Block and Run services. 
Block and Run are costly on a character-by-character basis; the cost 
is one or more task switches per character I/O. Timer handlers are 
required to save and restore registers. 

While a timer handler is in the format of a FAR CALL/RET routine, it 
operates at Interrupt time. The timer handler is analogous to the user 
timer (INT 1CH) handler. Care must be taken not to remain in the 
handier very long. 

For a new timer handler, TickCount will register the timer handler to 
be called on every N timer ticks instead of every timer tick. 



offset to timer liandler 
N ticl< counts (O-FFFF) 
0 means FFFFH+1 ticlts 
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Modify timer 



For a previously registered timer handler, TickCount changes the 
number of ticks that must take place before the timer handler gets 
control. This will allow device drivers to support the timeout function 
without needing to count ticks. 

At task time, this DevlHIp may be used to modify a timer handler reg- 
istered through SetTimer or may be used to register a new timer 
handler that is initially invoked every N ticks. 

In user mode (task time), this DevHIp may be used only to modify a 
timer handler already registered. 

In interrupt mode (interrupt time), this DevlHIp may be used only to 
modify a timer handler already registered. This allows an interrupt 
handler to reset the timing condition at interrupt time. 

Note that SetTimer sets a default of N ticks to 1. Multiple TickCount 
requests may be issued for a given timer handler, but only the last 
TickCount setting will be in effect. 

TickCount affects only the specified registered timer handler. It has 
no effect on other timer handlers. 

DS should be set to the device driver's data segment. If the device 
driver did a PhysToVirt referencing the DS register, it should restore 
DS to the original value. 

Timer handlers are responsible for saving and restoring registers on 
entry and exit. 

A maximum of 32 different timer handlers are available in the system. 
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Unlock 

Memory Segment 



Purpose 

This service unlocl^s a loclced memory segment. 



Processing 

MOV BX.lock.handleJow 
MOV AXJock_hancne_high 
MOV DL,DevHlp_Unlock 
CALL [Device_Help] 



Results 

'C Cleared if no error. 
'C Set if error. 

Invalid handle or cannot unlock memory. 



Remarks 

UnLoci< cannot be used on memory allocated by AllocPhys. 



; Handle for segment 
; returned by Lock 
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UnPhysToVirt 
Mark Completion of Virtual Address Use 



Purpose 

UnPhysToVirt is required to mark completion of address conversion 
from PhysToVirts. 

Processing 

MOV DL,DevHlp_UnPhysToVirt 
CALL [Device_Help] 

Results 

'Z' Cleared if no address mode change. 
'Z' Set if address mode change. 

Remarks 

This function forms part of the structure of mode-dependent 
addressing on behalf of a device driver, relieving it of the need to 
understand the CPU mode and the subsequent effects on accessing 
memory. 

On the PS/2, if the converted address caused a switch to the OS/2 
mode in PhysToVirt, UnPhysToVirt will switch back to the DOS mode. 

UnPhysToVirt must be called by the same procedure that issued the 
PhysToVirt when use of converted addresses is completed and before 
the procedure returns to its caller. The procedure that called 
PhysToVirt may call other procedures before calling UnPhysToVirt. 
Multiple PhysToVirt calls may be issued prior to issuing the 
UnPhysToVirt. Only one call to UnPhysToVirt is needed. 

The ZF is set if a mode switch occurred. This allows the device driver 
to recalculate any stored pointers that were not used in the data 
transfer operations with the PhysToVirt. 
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UnPhysToVirt 

Mark Completion of Virtual Address Use 



UnPhysToVirt, if switched to the DOS mode, will reset the registers 
CS and SS to the DOS mode. 

SP will be preserved. 

DS will be reset to the device driver's data segment. 

Note that the addresses that caused the switch into the OS/2 mode 
cannot be preserved or converted for the DOS mode. 

The ES register will not be preserved. The ES register is also set to 
the device driver data segment. 
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UnSetlRQ 

Remove Hardware Interrupt Handler 



Purpose 

This routine removes tlie current liardware interrupt handler. 
Processing 

MOV BX,IRQnum ;IRQ Interrupt number 

; ( 0 - F ) 

MOV DL,DevHlp_UnSetIRQ 
CALL [Device_Help] 

Results 

'C Set if caller is not the owner of 
or one of tlie owners of the IRQ. 

Remarks 

DS must point to the device driver's data segment on entry. 
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VerifyAccess 

Verify Access to Memory 



Purpose 

This routine verifies that the user process has the correct access 
rights for the memory that it passed to the device driver. 



Processing 



MOV 
MOV 

MOV 
MOV 



AX,Segment_(a 
CX.MemLength 

DI,Mem_Offset 
DH.TypeOf Access 



MOV DL,DevHlp_VerifyAccess 
CALL [Device_Help] 



Selector or segment 

Length of memory area 
in bytes (0 means 64 KB) 

Offset to memory area 

Verify access for 
= 0 read access 
= 1 read/write access 



Resuits 



'C Clear if no error 
Access verified. 

'C Set if error 

Access attempt failed. 



Remarlcs 

A device driver can receive addresses to memory as part of a generic 
lOCtI request from a process. Because the operating system cannot 
verify addresses imbedded In the lOCtI command, the device driver 
must request verification in order to prevent itself from accidentally 
erasing memory on behalf of a user process. If the verification test 
fails, then VerifyAccess will terminate the process. 

Note that verification may only take place in the OS/2 mode. If 
VerifyAccess is called In the DOS mode, it will return stating that the 
memory is accessible. 
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VerifyAccess 
Verify Access to Memory 



Once the process has been verified as having the needed access to a 
specific address location, the device driver doesn't need to request 
access verification each time it yields the CPU during task-time proc- 
essing of this process's request. If the process makes a new request, 
then the device driver must request access verification. 

Note also that, prior to requesting a Lock on user process-supplied 
addresses, the device driver must verify the user process's access to 
the memory with the VerifyAccess DevHIp call. The device driver 
must not yield the CPU between the VerifyAccess and the Lock, other- 
wise the user process could shrink the segment before it has been 
locked. Once the user access has been verified, the device driver 
may convert the virtual address to a physical address and lock the 
memory. The access verification is valid for the duration of the lock. 
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VirtToPhys 

Map Virtual Address to Physical Address 



Purpose 

When in the OS/2 mode, it converts a selector-offset pair to a 32-bit 
physical address. When in the DOS mode, VirtToPhys converts a 
segment-offset pair to a 32-bit physical address. 

Processing 

LDS SI, address 

MOV DL,DevHlp_VirtToPhys 
CALL [Device_Help] 

Results 

'C Cleared to indicate no error. 

AX:BX Physical address: 32-bit number. 

Remarks 

The virtual address should be locked by way of the DevHIp service 
Lock prior to invoking this function, if the segment is not known to be 
locked already. 

This function is typically used to convert a virtual address supplied by 
a process by way of a generic lOCtI, in order that the memory may be 
accessed at interrupt time. 



; Virtual address: 

; segment: offset or selector: offset 
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Yield 

Relinquish the CPU 



Purpose 

This routine yields tlie CPU to a scheduled thread of equal or higher 
priority. 

Processing 

MOV DL,DevHlp_YieTd 
CALL [Device.Help] 

Results 

None 

Remarks 

OS/2 is designed so that the CPU is never preemptively scheduled 
while In kernel mode. In general, the kernel either performs its job 
and exits quickly, or it blocks waiting for (usually) I/O or (occa- 
sionally) a resource. It Is not necessary for the device driver to do 
both a Yield and a TCYIeld; the Yield function Is a superset of the 
TCYield function. 

The one part of the kernel that can take a lot of CPU time Is In device 
drivers, particularly those that perform program I/O on long strings of 
data or poll the device. These drivers should periodically check the 
Yield Flag and call the Yield function to yield the CPU if another 
process needs it. Much of the time the context won't switch; Yield 
switches context only if an equal or higher priority thread Is sched- 
uled to run. 

The address of the Yield Flag is obtained from the GetDOSVar call. 
Refer to "GetDOSVar Get Address of Important DOS Variables" on 
page 8-29. 
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Yield 

Relinquish the CPU 



For performance reasons, the device driver sfiould clieol< tlie Yield 
Flag once every 3 milliseconds. If the flag is set, then the device 
driver should call Yield. 

Because the device driver may relinquish control of the CPU to 
another thread, the device driver should not assume that the state of 
the interrupt flag will be preserved across a call to Yield. 
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Chapter 9. Device Drivers 



The device drivers provided with OS/2 service requests in both the 
DOS mode and the OS/2 mode. Where appropriate, OS/2 device 
drivers provide a queued request interface rather than the serial 
request design of DOS device drivers. OS/2 device drivers support 
multitasking. 

This chapter references the lOCtI interface. The lOCtI interface 
allows an application or subsystem to send device-specific control 
commands to the device driver. The lOCtI function uses the 
DosDevlOCtI function request for OS/2 applications and the INT 21 H 
lOCtI request for DOS applications. See Technical Reference, Vol. 2 
for a detailed description of the DosDevlOCtI function request and the 
lOCtI functions. 



ASYNC (RS232-C) Communications Device Driver 

The Asynchronous Communications (ASYNC) device driver enables 
application programs or system programs (for example, Print 
Spooler) to utilize the RS232-C interface of the system in the OS/2 
mode. The device driver will allow an application program In the 
OS/2 mode to support full duplex communications while the device 
driver: 

• Services the RS232-C port In an Interrupt-drlven manner. 

• Provides transmit and receive queues. 

• Provides different automatic control modes of the modem control 
signals. 

• Provides logical data stream flow control (XON/XOFF) for transmit 
and receive. 

The ASYNC device driver can be installed optionally by the user via a 
DEVICE = command in CONFIG.SYS. This device driver uses up low 
memory, making that memory unavailable to DOS mode programs; 
therefore, this device driver should not be Installed unless it Is 
required. 
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The user will normally want to use the ASYNC device driver either in 
conjunction with the Print Spooler (if a serial printer is to be used), or 
with an application program that utilizes the RS232 enabling capabili- 
ties of the ASYNC device driver coupled with a serial device attached 
to the system. 

Hardware Support 

Supported hardware for the RS232-C ASYNC communications device 
driver includes: 

• The IBM Personal Computer AT and IBM Personal Computer XT 
Model 286. The IBM Personal Computer AT Serial/Parallel 
Adapter card (#0215, #3395, and #3400) is the supported adapter. 

• The PS/2 family computers (Models 50, 60 and 80). 
Personal Computer AT Adapter Support 

On the Personal Computer AT, the device driver supports a maximum 
of two ASYNC ports, each on separate interrupt levels. The device 
driver will recognize ASYNC ports with the following base I/O 

addresses: 

• 3F8H (must generate a level 4 interrupt) 

• 2F8H (must generate a level 3 Interrupt). 

No other base I/O addresses will be recognized or supported, and no 
other interrupt level combinations are supported. 

The ASYNC device driver for the Personal Computer AT interfaces 
directly to the hardware. 

PS/2 Adapter Support 

The ASYNC device driver for the PS/2 uses the Advanced BIOS inter- 
face for the ASYNC device. It does not interface directly to the hard- 
ware and does not support any device which requires direct 
hardware access. 
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The device driver supports a maximum of three ASYNC ports on a 
maximum of two different interrupt levels. The interrupt levels must 
have Advanced BIOS support, with one unit per Logical ID (LID) for 
the ASYNC device ID. 

The only ASYNC devices supported on PS/2 are C0M1, COM2, and 
COM3. These devices correspond to the first three LIDs in the 
Advanced BIOS common data area that have the architected ASYNC 
device ID. These devices also correspond to the first three ASYNC 
addresses in the ASYNC 40: area. 

If a device has capabilities other than ASYNC which cannot be uti- 
lized independently (for example, as in the Advanced BIOS separate 
LID architecture, and others) of the ASYNC capabilities, and if 
Advanced BIOS assigns that device the ASYNC device ID, then that 
device can only be used for ASYNC in that power-on session. 

If the device is not assigned the ASYNC device ID, it is not supported 
by this device driver. 

If the device is assigned the ASYNC device ID and it has additional 
capabilities (for example, a built in modem) beyond supporting the 
RS232-C port, the device driver will not recognize those additional 
capabilities (and potential limitations). Also, the device driver will 
not inform any application program of those additional capabilities (or 
limitations). And the device driver will not limit the control of the 
RS232-C interface or the device to only those modes which are 
acceptable to the extended hardware capabilities of that RS232-C 
port. 

If an ASYNC device is not supported by OS/2 but is recognized by 
Advanced BIOS as an ASYNC device ID, the device driver may recog- 
nize and try to use that unsupported device if it is C0M1, COM2, or 
COM3. 

Attachment Support 

The ASYNC device driver does not provide any support for devices 
attached to the RS232-C port. The device driver provides enabling 
support for the RS232-C interface itself. Application programs, sub- 
systems, and systems programs provide the support needed to use 
devices attached to the RS232-C port. 
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The ability to support a device can be determined by understanding 
the level of RS232-C interface enabling support the device driver pro- 
vides, along with the characteristics of the attachment hardware in 
question and the required functions to be supported. 

The ASYNC device driver provides a mechanism where one or more 
additional device drivers can be installed to support specific COM 
ports. This feature may be required for the following reasons: 

• To allow an application program to support a special device not 
adequately supportable with this ASYNC device driver. 

• To allow additional COM ports (besides C0M1-3 on PS/2) to be 
supported. 

• To enhance the level of device driver function for a given COM 
port. (This may be required for certain subsystem support.) 

RS232-C Interface 

The ASYNC interface consists of separate read and transmit lines. 

There are two separate modem control signals whose output values 
can be controlled by the device driver: 

• Data Terminal Ready (DTR) 

• Request To Send (RTS). 

There are four separate modem control signals whose Input values 
are available to the device driver: 

• Data Set Ready (DSR) 

• Clear To Send (CTS) 

• Data Carrier Detect (DCD) also known as Receive Line Signal 
Detect (RLSD) 

• Ring Indicator (Rl). 

The receive and transmit data lines have the following hardware 
characteristics: 

• Logical 1 - Marking - More negative than -3 Volts. This state 
could mean no data. 

• Logical 0 - Spacing - More positive than +3 Volts. This state 
could mean break condition. 
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The modem control signal lines iiave the following hardware 
characteristics: 

• Function ON when more positive than +3 Volts. 

• Function OFF when more negative than -3 Volts. 

RS232-C Enabling Characteristics 

The device driver supports the ASYNC interface in an interrupt-driven 
manner. This allows the multitasking capabilities of OS/2 to be sup- 
ported while ASYNC data reception and transmission is taking place. 

With the current ASYNC hardware, when data is given to the transmit 
hardware, data will be transmitted at the physical RS232-C interface. 
When data is given to the transmit hardware, it has not yet been phys- 
ically transmitted (at the RS232 interface). The data is considered 
completely transmitted by the transmit hardware at the physical 
RS232 interface when the transmit shift register of the UART is empty. 
The lOCtI Return Transmit Data Status (Category 1 Function 65H) can 
be used to determine this information. 

The device driver transmit queue is a memory buffer between the 
OS/2 system and the transmit hardware. It is considered to be owned 
by the device driver because the device driver controls the data 
movement into and out of the transmit queue. Algorithms for this 
data movement may change between releases of the device driver. 
Changes in the ASYNC hardware may cause changes in the data 
movement algorithms and/or external interfaces. 

The device driver receive queue is a memory buffer between the 
OS/2 system and the receive hardware. It is considered to be owned 
by the device driver because the device driver controls the data 
movement into and out of the receive queue. Algorithms for this data 
movement also can change between releases of the device driver. 
Changes in the ASYNC hardware can cause changes in the data 
movement algorithms and/or external interfaces. 

Data that applications send (made available by Write requests) get 
placed in the device driver transmit queue. When an interrupt occurs 
to tell the device driver that the hardware is ready for more data, the 
device driver will give the transmit hardware more data from the 
transmit queue. 
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When an interrupt occurs to tell the device driver that the hardware 
has received data, that data Is placed in the device driver receive 
queue. When the device driver gets a read request (Read request 
packet) from the application, the device driver fills the read request 
from the receive queue. 

The size of the receive and transmit queues are available from the 
following lOCtIs: 

• Return number of chars in receive queue 
(Category 1 Function 68H). 

• Return number of chars in transmit queue 
(Category 1 Function 69H). 

The device driver services each communications port Independently. 
Requests issued to a given port have no effect on any other communi- 
cations ports that the device driver may be servicing. 

The device driver processes Read and Write request packets inde- 
pendently for a given port. An application can be written to support 
simultaneous reception and transmission of data. In addition, the 
device driver can process an lOCtI request simultaneously with out- 
standing Read and Write requests. 

The device driver does not schedule the processing of lOCtI requests. 
The device driver processes the lOCtI request when received, regard- 
less of what else It is doing. This may cause unexpected results if, 
for instance, the baud rate is modified while data reception or trans- 
mission is taking place. 

The application should issue only one lOCtI request at a time. If the 
application issues another lOCtI request before the first iOCtI request 
completes, the results are UNDEFINED. 

The device driver will queue multiple Read and Write request packets 
independently. The device driver always will begin processing the 
Read request packets in the order that they are received. It will 
always begin processing the Write request packets in the order that 
they are received. 

Note: The operating system does not guarantee that file system 
requests will be delivered to a device driver in the order in which 
they are Issued by an application. This means that a request by one 
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thread can get blocked in the operating system, thus allowing a sul>- 
sequent request by a different thread for the same function (for 
example, DosWrite) to pass through and arrive ahead of the first 
thread at the device driver. This is true for synchronous operations 
performed by multiple threads, or asynchronous operations per- 
formed by the same thread. 

Because of thread priority considerations and the system dynamics, 
the order observed by the application of completing requests of the 
same type may not be In the order that they were received by the 
device driver. The device driver will always l<eep the data In the 
same order in which the Read and Write request packets (of the same 
type) were received in. There is no ordering or timing between dif- 
ferent types of request packets. 

A First Level Open is described in the section on "States of the 
ASYNC Device Driver" on page 9-11. A First Level Open occurs 
when the device driver receives an OPEN request packet for the port 
and the port is not already open (from a previous open without a 
matching close). A CLOSE request packet causing the device driver 
to process the next OPEN request packet as a First Level Open, is 
called a last level close. Because the requests that an application 
issues sometimes get out of order before they reach the device 
driver, an application cannot consider a CLOSE a last level CLOSE 
until the CLOSE completes. If the application Issues an OPEN 
request to the COM port before a previously issued CLOSE request is 
completed, then the results are UNDEFINED. 

The Flush request may be completed before all the appropriate 
request packets (that have been queued by the device driver) have 
been flushed. The appropriate request packets will eventually be 
flushed (and return to the caller) based on their priority and the 
system dynamics. Once the Flush request has been processed, the 
appropriate request packets will not cause data to be transmitted (or 
received data to be moved) incorrectly. 

The device driver supports different time-out processing character- 
istics and time-out settings for the Read and Write requests. 

The device driver removes from an application how to know exactly 
when a given character is being transmitted or received (at the hard- 
ware interface). Therefore, an application cannot expect to provide 
real-time flow control of data (in the middle of data transmission or 
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reception) based on logical characters (XON/XOFF) or based on the 
state of the modem control signals by: 

• Manually controlling or monitoring those modem control signals 

• Manually monitoring the queue status 

• Manually monitoring data moving across the link. 

Therefore, the device driver provides automatic modes of operation 
that are controllable via lOCtIs, to allow OS/2 mode applications 
automatically to control the data flow through the RS232-C port. 

Output Modem Control Signals 

Besides allowing the application to control directly RTS and DTR, the 
device driver has different automatic control modes to control the 
value of the output modem control signals. They are: 

• Open and Close processing of DTR and RTS 

• Disable/Enable DTR & RTS 

• RTS toggling on transmit 

• Input handshaking using DTR & RTS. 

These different control modes are described in the section on "States 
of the ASYNC Device Driver" on page 9-11 and in the lOCtIs 
description. 

Note: The level of support provided by this device driver requires 
that DTR and RTS are turned on at least once, even if this puts the 
device driver in a mode where they will never be turned on again. 

Input Modem Control Signals 

Besides allowing the application to read directly the current state of 
DSR, CTS, DCD, and Rl, the device driver has different automatic 
modes that cause it to respond to the value that some input modem 
control signals may have. They are: 

• Output handshaking using CTS, DSR, DCD 

• Input sensitivity using DSR. 

These different control modes are described in the section on "States 
of the ASYNC Device Driver" on page 9-11 and in the lOCtIs 
description. 
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Additional information on tine state of tiie input modenn control signals 
is available by using the lOCtI Return COM Event Information (Cate- 
gory 1 Function 72H). 

Logical Flow Control (XON/XOFF) 

The application can attempt to manually control the flow of data by 
using the following lOCtIs: 

• Transmit Immediate (Category 1 Function 44H) 

• Stop Transmit behave as if XOFF received 
(Category 1 Function 47H) 

• Start Transmit behave as if XON received 
(Category 1 Function 48H). 

The device driver also will control automatically the flow of trans- 
mitted data based upon the reception of XON/XOFF characters. This 
is referred to as automatic transmit flow control (XON/XOFF) and is 
described in the section on "States of the ASYNC Device Driver" on 
page 9-11. 

The device driver also will attempt to control the flow of data that is 
received by automatically transmitting XON/XOFF characters to the 
system it is communicating with, based on the amount of space left in 
the receive queue. This is referred to as automatic receive flow 
control (XON/XOFF) and is described in the section on "States of the 
ASYNC Device Driver" on page 9-11. 

Line Characteristics 

lOCtIs can be used to control and read the baud rate, number of stop 
bits per character, number of data bits per character, and the parity 
characteristics of the line. See the section on "States of the ASYNC 
Device Driver" on page 9-11. 

Break and Error Processing, Port Status, Rl 

The device driver can be commanded to transmit a Break with an 
lOCtI (Category 1 Function 4BH and Function 45H). 

An application can detect where an error or breal^ occurred in the 
input data stream by using Breal^ Replacement Character Processing 
and Error Replacement Character Processing. This requires certain 
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binary byte combinations to be reserved for this purpose. See tlie 
section on "States of the ASYNC Device Driver" on page 9-11. 

State of the COM Port 

The following lOCtis can be used to determine the state of the COM 
port or if a given event happened. However, the exact timing 
relationship between this information and the specific data being 
received or transmitted at the time of the event Is not available. 

• Return COM Event Information (Category 1 Function 72H) 

• Return COM Status (Category 1 Function 64H) 

• Return COM Error (Category 1 Function 6DH). 

Event Notification 

The device driver does not provide any capabilities of event notifica- 
tion. For example, the only way for an application to know that Rl 
changed state or that a Break condition occurred is to poll that status 
with the lOCtI Return COM Event Information. This should not be a 
problem for those applications that can use the automatic control 
modes of the device driver during the course of a communications 
dialog (for time-critical control functions). Polling could be adequate 
for non-time-crltlcal event monitoring. 
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states of the ASYNC Device Driver 

This section itemizes the different processing states of the ASYNC 
device driver, the ASYNC hardware, and the ASYNC control signals. 

The items that will be discussed are: 

• Baud Rate 

• Data Bits 

• Parity 

• Stop Bits 

• DTRandRTS 

• DTR Control Mode 

• RTS Control Mode 

• Transmitting Break 

• Event Word and COM Error 

• COM Error 

• Output handshaking using CTS, DSR, DCD 

• Input sensitivity using DSR 

• Automatic Transmit Flow Control (XON/XOFF) 

• Automatic Receive Flow Control (XON/XOFF) 

• XON/XOFF Characters 

• Error Replacement Character Processing 

• Error Replacement Character 

• Break Replacement Character Processing 

• Break Replacement Character 

• Null Stripping 

• Write Time-out State 

• Write Time-out Value 

• Read Time-out State 

• Read Time-out Value 

• Transmit Immediate 

The following will be given for each Item: 

• A brief description. 

• The initial (default) value. 

• The device driver effect when the device driver receives an OPEN 
request packet for the port and the port Is not already open (from 
a previous open without a matching close). This is called a First 
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Level Open. If applicable, the way the state of the device driver 
Is affected by a close request packet. 

• The MODE utility (in the OS/2 mode) used to alter the state of this 
item or the MODE utility (In the OS/2 mode) altering the state of 
this item. 

Baud Rate 

Baud rate is the speed for which the hardware is configured. See 
lOCtls "Set Baud Rate" (Category 1 Function 41 H) and "Return 
Current Baud Rate" (Category 1 Function 61 H). 

Initial Value - 1200 baud. 

First Level Open - No effect. 

Mode Utility - User interface to change the baud rate. 
Data Bits 

The number of bits that are contained in each character transmitted 
or received by way of the communications hardware. See lOCtIs "Set 
Line Characteristics" (Category i Function 42H) and "Return Line 
Characteristics" (Category 1 Function 62H). 

Initial Value - 7 data bits. 

First Level Open - No effect. 

Mode Utility - User interface to change the number of data bits. 
Parity 

Determines whether a parity bit exists and (if appropriate) what algo- 
rithm determines its value. See lOCtIs "Set Line Characteristics" 
(Category 1 Function 42IH) and "Return Line Characteristics" (Cate- 
gory 1 Function 62H). 

Initial Value - Even Parity. 

First Level Open - No effect. 

Mode Utility - User interface to change the parity characteristics. 
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stop Bits 

Determines the number of stop bits associated with each character 
transmitted or received by way of the communications hardware. 
See lOCtIs "Set Line Characteristics" (Category 1 Function 42H) and 
"Return Line Characteristics" (Category 1 Function 62H). 

Initial Value - 1 stop bit. 

First Level Open - No effect. 

Mode Utility - User interface to change the number of stop bits. 
DTR & RTS 

The value of the modem control signals Data Terminal Ready (DTR) 
and Request To Send (RTS) put out by the communications hardware. 
Each signal is controlled independently and can be either ON or OFF. 
See lOCtIs "Set Modem Control Signals" (Category 1 Function 46H) 
and "Return Modem Control Output Signals" (Category 1 Function 
66H). 

Initial Value - When the device driver starts the port during device 
driver initialization, their values will be turned off. 

First Level Open - The signals are normally turned on but there are 
many conditions that may cause the signals to be affected differ- 
ently. See lOCtIs "Set Modem Control Signals" (Category 1 Func- 
tion 46H) and "Set Device Control Block" Information NOTE 1 
(Category 1 Function 53H) for a complete explanation. 

Close Considerations - A close request packet, when after processing 
this close request the port will not be open any more from another 
open without a close (last level close), will cause DTR and RTS to 
be turned OFF after the transmit hardware has completely trans- 
mitted all the data that it has been given to transmit by the device 
driver and at least 10 additional character times have elapsed. 

Mode Utility - Not applicable for direct control. Indirect effects 
through altering processing modes of the device driver are pos- 
sible. 
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DTR Control Mode 

The different control modes for DTR are: 

• Enable 

• Disable 

• Input Handshaking 

The Enable and Disable control modes of DTR affect DTR processing 
during a First Level Open. When these control modes are set via the 
Category 1 Function 53H lOCtI, the value of the DTR signal may be 
modified immediately by the device driver. The action will depend on 
the previous control mode of DTR and the current value of the DTR 
modem control signal. If the control mode of DTR Is input Hand- 
shaking, then the device driver will control the DTR signal, depending 
on how full the receive queue is. The bits that control these states of 
the device driver are in the device control block. See lOCtIs "Set 
Modem Control Signals" (Category 1 Function 46H) and "Set Device 
Control Block Information" NOTE 1 (Category 1 Function 53H). 

Initial Value - Enable. 

First Level Open - No effect. 

Mode Utility - User interface to change the DTR Control Mode of the 
device driver. 

RTS Control Mode 

The different control modes for RTS are: 

• Enable 

• Disable 

• Input Handshaking 

• Toggling on Transmit 

The Enable and Disable control modes affect RTS processing during 
a First Level Open. When these control modes are set using the Cat- 
egory 1 Function 53H lOCtI, the value of the RTS signal may be imme- 
diately modified by the device driver. The action will depend on the 
previous control mode of RTS and the current value of the RTS 
modem control signal. If the control mode of RTS is Input Hand- 
shaking, the device driver will control the RTS signal, depending on 
how full the receive queue is. If the control mode of RTS is Toggling 
on Transmit then the device driver will control the RTS signal, 
depending on whether it transmits data. The bits that control these 
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states of the device driver are in the device control blocl<. See lOCtIs 
"Set Modem Control Signals" (Category 1 Function 46H) and "Set 
Device Control Block Information" NOTE 1 (Category 1 Function 53H). 

Initial Value - Enable. 

First Level Open - No effect. 

Mode Utility - User interface to change the RTS Control Mode of the 
device driver. 

Transmitting Brealc 

The device driver can be transmitting a break. See lOCtIs Break On 
(Category 1 Function 4BH) and Break Off (Category 1 Function 45H). 

Initial Value - Not transmitting a break. 

Close Considerations - A CLOSE request packet, when after proc- 
essing this close request the port will not be open any more from 
another open without a close (last level close), will cause the 
device driver to tell the hardware not to transmit a break any 
more. 

Mode Utility - Not applicable. 

COM Event Word and COM Error Word 

These two words have bits which show status of the COM port. When 
an event happens the appropriate bits are turned on. The bits are 
cleared when the word is read with the appropriate lOCtl. See lOCtI 
Return COM Event Information (Category 1 Function 72H) and Return 
COM Error (Category 1 Function 6DH). 

Initial Value - All defined bits are 0. 

First Level Open - All defined bits are 0. 

Mode Utility - Not applicable. 

Output Handshaidng using GTS, DSR, DCD 

This mode of the device driver can be controlled independently for 
each modem control signal. When this mode of the device driver is 
enabled, the device driver will not give data to the transmit hardware 
if the appropriate modem control signal is OFF. See lOCtI "Set 
Device Control Block" Information NOTE 3 (Category 1 Function 53H). 
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initial Vaiue - Output iiandslial^ing using CTS and DSR is enabled. 
Output handshaking using DCD Is disabled. 



First Level Open - No effect. 

Mode Utility - User interface to enable/disable this mode of the device 
driver for CTS and DSR (independently). Mode will always 
disable this mode of operation of the device driver for DCD. 

Input Sensitivity Using DSR 

When the device driver is enabled for this mode of operation and DSR 
is OFF, the device driver will discard receive data. See lOCtI "Set 
Device Control Block Information" NOTE 4 (Category 1 Function 53H). 

Initial Value - Input Sensitivity using DSR is enabled. 

First Level Open - No effect. 

Mode Utility - User interface to enable/disable this mode of the device 
driver. 

Automatic Transmit Fiow Control (XON/XOFF) 

When the device driver is enabled for this mode of operation, the 
device driver will stop sending data to the transmit hardware when an 
XOFF is received, and resume sending data to the transmit hardware 
when an XON is received. See lOCtI "Set Device Control Block 
Information" NOTE 2 (Category 1 Function 53H). 

Initial Value - Automatic transmit flow control is disabled. 

First Level Open - No effect on whether the device driver is enabled 
or disabled for this mode of operation. The state of the device 
driver will be reset to show that it has not received an XOFF so it 
can transmit (due to automatic transmit flow control) if it is 
enabled for this mode of operation. 

Mode Utility - User interface to enable/disable this mode of the device 
driver. 
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Automatic Receive Flow Control (XON/XOFF) 

When the device driver is enabled for this mode of operation, the 
device driver will transmit an XOFF when its receive queue gets close 
to full, and an XON when its receive queue is about half full. See 
lOCtI "Set Device Control Block" Information NOTE 2 (Category 1 
Function 53H). 

Initial Value - Automatic Receive Flow Control Is disabled. 

First Level Open - No effect on whether the device driver is enabled 
or disabled for this mode of operation. The state of the device 
driver will be reset to show that the last flow control character 
automatically transmitted was an XON if it is enabled for this 
mode of operation. 

Close Considerations - If the last automatically transmitted character 
by the device driver was an XOFF and a CLOSE request packet is 
received, (when after processing this close request the port will 
not be open any more from another open without a close - Last 
Level Close), the device driver will automatically transmit an XON, 
if possible. 

Mode Utility - Always disables Automatic Receive Flow Control. 
XON/XOFF characters 

The characters used for automatic transmit and automatic receive 
flow control. See lOCtI "Set Device Control Block Information" NOTE 
2 (Category 1 Function 53H). 

Initial Value - XON is 11H and XOFF is 13H. 

First Level Open - The XON and XOFF characters are reset to their 
initial values. 

Mode Utility - No effect. 

Error Replacement Character Processing 

The processing that the device driver performs when a received char- 
acter had an error (parity, framing, overrun, or lack of receive queue 
space) is determined by whether error replacement character proc- 
essing is enabled (active). See lOCtI "Set Device Control Block 
Information" NOTE 5 (Category 1 Function 53H). 

Initial Value - Error replacement character processing is disabled. 
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First Level Open - Error replacement character processing is disa- 
bled. 

Mode Utility - No effect. 
Error Replacement Character 

The character value that the device driver uses if Error Replacement 
Character Processing is enabled. See lOCtI "Set Device Control 
Block Information" NOTE 5 (Category 1 Function 53H). 

Initial Value - OOH. 

First Level Open - Reset to OOH. 

Mode Utility - No effect. 

Break Replacement Character Processing 

If break replacement character processing is enabled, and the device 
driver detects a break condition, it will place the break replacement 
character in the device driver receive queue. If break replacement 
character processing is disabled, the device driver will not place any 
character in the device driver receive queue when it detects a break 
condition. See lOCtI "Set Device Control Block Information" NOTE 7 
(Category 1 Function 53H). 

Initial Value - Break replacement character processing is disabled. 

First Level Open - Break replacement character processing is disa- 
bled. 

Mode Utility - No effect. 
Break Replacement Character 

The character value that the device driver uses if Break Replacement 
Character Processing is enabled. See lOCtI "Set Device Control 
Block Information" NOTE 7 (Category 1 Function 53H). 

Initial Value - OOH. 

First Level Open - Reset to OOH. 

Mode Utility - No effect. 
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Null Stripping 



If the device driver is enabled for null stripping, characters read in 
from the receive hardware (non error or non break) with a value of 
OOH are thrown away. These null characters are stripped (not 
checked for Automatic Transmit Flow Control) even if the XON or 
XOFF character has been set to OOH, and are not placed in the device 
driver receive queue. See lOCtI "Set Device Control Block 
Information" NOTE 6 (Category 1 Function 53H). 

Initial Value - Null stripping is disabled. 

First Level Open - Null stripping is disabled. 

Mode Utility - No effect. 

Write Time-out State 

When the device driver processes a WRITE request packet, it can be 
with normal or infinite time-out processing. With normal time-out 
processing, if no data is given to the transmit hardware within a spec- 
ified amount of time, the request will be completed. With infinite 
time-out processing, the request will be completed only when all the 
data from the request has been given to the transmit hardware. See 
lOCtI "Set Device Control Block" Information NOTE 8 (Category 1 
Function 53H). 

Initial Value - Normal Write time-out processing. 

First Level Open - No effect on write time-out processing. 

Mode Utility - User interface to set infinite or normal write time-out 
processing. 

Write Time-out Value 

The user specific value, in .01 seconds units (based on 0, where 0 = 
.01 seconds), is used for the write time-out processing, if normal write 
time-out processing is enabled. See lOCtI "Set Device Control Block 
Information" NOTE 8 (Category 1 Function 53H). 

Initial Value - 1 Minute. 

First Level Open - Set to 1 Minute. 

Mode Utility - No effect. 
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Read Time-out State 

When the device driver processes a READ request pacl^et, it can be 
with normal, with NO-WAIT, or with Wait For Something time-out 
processing. With normal time-out processing, if no data is received 
in the specified period of time, the request will be completed. With 
NO-WAIT time-out processing, the request will obtain whatever data 
is available in the device driver receive queue (at the time the 
request is processed by the device driver) and return. With Wait-For- 
Somethlng time-out processing, the request will act like NO-WAIT 
time-out processing. However, if no data is available when the 
device driver processes the request, the device driver. will wait until 
some data is available or until the request times out due to normal 
time-out processing. See lOCtI "Set Device Control Block 
Information" NOTE 9 (Category 1 Function 53H). 

Initial Value - Normal Read time-out processing. 

First Level Open - The device driver Is set to Normal Read Time-out 
processing. 

Mode Utility - No effect. 
Read Time-out Value 

The user specific value, in .01 seconds units (based on 0, where 0 = 
.01 seconds), is used for the read time-out processing, if normal read 
time-out or Wait For Something time-out processing is enabled. See 
lOCtI "Set Device Control Block" Information NOTE 9 (Category 1 
Function 53H). 

Initial Value - 1 Minute. 

First Level Open - Set to 1 Minute. 

Mode Utility - No effect. 

Transmit immediate 

The device driver may be told to transmit a byte immediately, 
bypassing the normal file system write requests (bypassing the data 
to be transmitted in the transmit queue). Only one character at a time 
can be waiting to be transmitted "immediately." See lOCtI "Transmit 
This Byte Immediately" Category 1 Function 44H. 
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Initial Value - Tliere is no character waiting to be transmitted imme- 
diately. 

First Level Open - There is no character waiting to be transmitted 
immediately. 

Close Considerations - A CLOSE request packet, when after proc- 
essing this close request the port will not be open any more (from 
another open without a close), will cause the device driver to 
attempt to transmit the character waiting to be transmitted imme- 
diately. If the device driver cannot transmit the character waiting 
to be transmitted immediately (See lOCtI "Transmit this Byte 
Immediately" Category 1 Function 44H), then it will not try to 
transmit the character and proceed with the close processing. 

Mode Utility - Not applicable. 
Reserved Device Names- C0M1-N 

The device name AUX does not appear in the Device Header of the 
ASYNC device driver. The ASYNC device driver does not support the 
reserved name AUX for either DOS mode applications or OS/2 mode 
applications. 

Personal Computer AT Considerations- COiMI, C0iM2 

The Personal Computer AT ASYNC device driver will have device 
names C0M1 and COM2 in its Device IHeader. 

Device name C0M1 will correspond to the ASYNC hardware with its 
base address in 40:0 (during initialization) and device name COM2 
will correspond to the ASYNC hardware with its base address in 40:2 
(during initialization). After the ASYNC device driver initialization, 
the contents of the 40: area are not monitored by the ASYNC device 
driver. The values in 40: are set to 0 for any COM port that is initial- 
ized. If these values are restored later in the same power on session, 
the integrity of the ASYNC device driver could be adversely affected 
by any process that directly accesses hardware through the 40: area. 

It should be noted that if the adapter card is configured as a sec- 
ondary COM port, the system may not always treat it as COM2. 

Note: The mapping of the 40: area to COMn must be consistent 
across all device drivers that support the ASYNC hardware in the 
Personal Computer AT hardware environment. 
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Refer to the SETCOM40 Utility for more Information. 
PS/2 Considerations- C0M1 - 3 

The PS/2 ASYNC device driver will have device names C0M1, COM2, 
and COM3 In its Device l-ieader. 

Device name C0M1 will correspond to the first LID in the Advanced 
BIOS common data area with the ASYNC device ID. Device name 
COM2 will correspond to the second LID and device name COM3 will 
correspond to the third LID In the Advanced BIOS common data area 
with the ASYNC device ID. The Advanced BIOS architecture ensures 
that the ordering in the 40: area will match the ordering of the LIDs In 
the common data area. Compatibility BIOS supports up to 4 ASYNC 
devices on PS/2 and the device driver assumes that the order of the 
Logical IDs match the order of the addresses of these devices In the 
40: area. 

Additional ASYNC devices may be supported by additional device 
drivers. 

The mapping of the ASYNC Logical ID ordering to COMn must be con- 
sistent across all device drivers that support the ASYNC hardware In 
the PS/2 hardware environment. 

Initialization / Resource Management 

The device driver is loaded and Initialized with a DEVICE = statement 
in CONFIG.SYS. The name of the device driver for the Personal Com- 
puter AT is COM01.SYS and the name of the device driver for the 
PS/2 is COM02.SYS. The device driver does not process any parame- 
ters on the DEVICE = statement. It is the responsibility of the Instal- 
lation process or the user to have the correct DEVICE = statement in 
the CONFIG.SYS file, depending on whether the OS/2 Is installed on: 

• IBM Personal Computer AT and IBM Personal Computer XT 
Model 286-COM01.SYS 

• IBM Personal System/2™ Models 50, 60, and 80 - COM02.SYS 

During initialization, the device driver will attempt to free memory 
from its data segment for ports it does not need to support. The 
device driver will not remove device names from its Device Header 
for ports that do not get initialized. 
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The device driver will not deinstall a device if the system requests it. 
If another device driver wishes to support a port already supported by 
this device driver, it needs to initialize before this ASYNC device 
driver. Taking the appropriate action, means this device driver will 
not prevent the other device driver from supporting the COM port in 
question. There are many ways this can be done, depending on the 
system. See initialization considerations below. 

Dynamic ownership of a given COM port between different device 
drivers in the same boot of OS/2 is not supported. Only one device 
driver can support a given COM port in a given boot of OS/2. 

If a supported port encounters a condition where it fails to initialize, a 
message will be displayed to indicate the nature of the condition. 

If installation fails due to errors for all supported ports, the system 
will display a message and pause, allowing corrective measures to 
be talcen. 

Personal Computer AT Initialization Considerations 

The device driver will not attempt to initialize or support a port if it 
does not get the INIT request packet for the port's corresponding 
device name. 

If the device driver gets the INIT request packet for a given device 
name it will check to see if a valid I/O address (2F8H or 3F8H) Is in 
the appropriate 40: area (that corresponds to that device name). 
C0M1 is 40:0 and COM2 is 40:2. 

If the 40: area does not have a valid I/O address, the device driver 
fails the initialization of this port and will not support this port. 

Otherwise, the device driver attempts to get exclusively the Interrupt 
level that corresponds to the I/O address for this port. If the interrupt 
level is not available, then the device driver fails the initialization of 
this port and will not support this port. 

If the interrupt level is available, then the device driver will give back 
the interrupt level, set to 0 the 40: area address for this port (this will 
normally prevent INT 14H from functioning for this port), initialize the 
port, and set up to support the port during this start-up of OS/2. 
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In summary, in order for the device driver to support a port on the 
Personal Computer AT, the following must be true: 

• The device driver must get an INIT request packet for the device 
name. 

• The 40: area that corresponds to the device name must have a 
valid I/O address. 

• The appropriate interrupt level must be available for exclusive 
use, even though the device driver will not claim the interrupt 
level for exclusive use during Initialization. 

The device driver claims ownership of the port by not DEINSTALLING 
the corresponding device name and by setting to 0 the corresponding 
40: area. 

Another device driver can cause this device driver not to claim a port 
by initializing before this device driver and doing at least one of the 
following: 

• Not allowing this device driver to receive an INIT request packet 
for a given device name. 

• Putting an invalid I/O address in the corresponding 40: area (for 
example, 0). 

• Owning exclusively the appropriate interrupt level at initialization 
time. 

PS/2 Initialization Considerations 

The device driver will not attempt to Initialize or support a port if it 
does not get the INIT request packet for the port's corresponding 
device name. 

If the device driver gets the INIT request packet for a given device 
name then It will attempt to claim ownership of the specific LID posi- 
tion for the ASYNC device ID that corresponds to the device name 
being initialized. 

If the LID is not available, then the device driver falls the initialization 
of this port and will not support this port. 

If the LID is available, then the device driver will initialize the port 
and set up support for this port during this start-up of OS/2. The 
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device driver will set to 0 the appropriate 40: area (tliis will normally 
not allow INT 14H to function for this port). 

In summary, for the device driver to support a port on PS/2, the fol- 
lowing must be true: 

• The device driver must get an INIT request packet for the device 
name. 

• The ASYNC LID corresponding to the device name must be avail- 
able. 

The device driver claims ownership of the port by not DEINSTALLING 
the corresponding device name and by claiming the appropriate 
ASYNC logical ID. The device driver also sets to 0 the corresponding 
40: area. 

Another device driver can cause this device driver not to claim a port 
by initializing before this device driver and doing at least one of the 

following: 

• Not allowing this device driver to receive an INIT request packet 
for a given device name. 

• Claiming the appropriate ASYNC LID. 
Access Authorization 

The device driver does not prevent multiple processes from concur- 
rently opening the same device name. This is the responsibility of 
the user or the subsystems that reside between the applications and 
the device driver. Allowing multiple processes to use (OPEN) concur- 
rently the same device name could cause unexpected results. 

Data Translation / iMonitor Support /Spooler Support 

The device driver provides no data translation, code page, or monitor 
support. It is the responsibility of the application or subsystem to 
provide any function required in these areas. 

Spooling from LPT to COM is supported by the print spooler but 
spooling from COM to LPT or COM to COM is not supported. The 
level of code page support provided by the print spooler is available 
through LPT and the print spooler. 
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Any requests for registering or opening a monitor cliain to COMn will 
be rejected by the device driver. 

The device driver deals with binary data and provides no special 
processing in the area of "binary" or "ASCII" mode. 

File System Requests 
open Processing 

The device driver does not claim the interrupt level the port is on until 
the port is open. If the interrupt level is not available, the Open 
request packet is failed. The interrupt level is claimed exclusively on 
the Personal Computer AT. The interrupt level is claimed shareable 
on PS/2. 

if a timer ticic handler is not available during First Level Open proc- 
essing, the open request may fail. 

If the device driver receives an OPEN request packet and the COM 
device is not already open (from a previous open without a close), the 
device driver does special processing. See "States of the ASYNC 
Device Driver". This is called a First Level Open. If a subsequent 
open request is issued before a previous First Level Open request 
has completed, the device driver may process the open request 
packets in a different order than they were issued. This could cause 
the First Level Open to take effect at a different time from what the 
application was expecting. 

An OPEN request should never be issued until a previous last level 
CLOSE request has completed. If an OPEN request is issued before a 
previous last level CLOSE has completed, the function performed by 
a last level close and a First Level Open may not occur. 

On the Personal Computer AT, if the port is not already open (First 
Level Open), the device driver will attempt to clear out any data in the 
receive hardware. On PS/2, if the port is not already open (First 
Level Open), the device driver will rely on the "reset / initialize" 
Advanced BIOS function to reset and clear the UART receive hard- 
ware. 
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Close Processing 



An application sliould never close an open handle to a COM port 
while there are requests outstanding to that handle. If a request has 
not completed, it nnay be waiting for time-out processing. lOCtIs may 
be used to determine the current time-out processing and to change 
the current time-out processing. 

If the device driver receives a CLOSE request packet, the device 
driver will do some special processing. When after processing this 
close request the port will not be open any more from another open 
without a close - Last Level Close. See "States of the ASYNC Device 
Driver" on page 9-11. The device driver, (when processing a close 
request that causes the port not to be open any more - Last Level 
Close), will: 

• Clear the receive and transmit queues. 

• Turn break off if currently transmitting a break. 

• Clear any character waiting to be transmitted immediately if it 
cannot be transmitted. If it can be transmitted, the device driver 
will make sure that it is given to the transmit hardware. 

• If currently enabled for automatic receive flow control 
(XON/XOFF) and the last character that the device driver auto- 
matically transmitted was an XOFF, the device driver will attempt 
to automatically transmit an XON, if possible. 

• Wait until all the data in the transmit hardware has been phys- 
ically transmitted. 

• Unclaim the interrupt level. 

• Turn DTR & RTS OFF if they are not already OFF. The device 
driver will wait the specified number of character times first (see 
"States of the RS232 Device Driver"). 
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Read Processing 



The device driver will begin processing Read requests in the order 
that they are received by the device driver. 

Note: This may not be the same order that the requests were issued 
by the application. If the device driver receives more than one Read 
request, the request packet will be queued on the Read request 
packet queue for later processing. 

Applications may not see read requests completed in the order that 
they were received by the device driver. The order of the data placed 
in the read requests will reflect the order the requests were received 
by the device driver. 

The data for the read requests comes from the device driver receive 
queue. Because of time-out processing, it is normal for the total 
number of read characters requested not to be read. This is not con- 
sidered an error. The request is completed when time out is com- 
pleted or when the amount of data requested is placed in the read 
buffer. 

The different kinds of Read Time-out processing are discussed in the 
"States of the ASYNC Device Driver" on page 9-11. 

To reduce the probability of a device driver receive queue buffer 
overrun, the communications protocol should take into account the 
size of the device driver receive queue. 

Write Processing 

The device driver will begin processing write requests in the order 
that they are received by the device driver. 

Note: This may not be the same order that the requests were issued 
by the application. If the device driver receives more than one write 
request, the request packet will be queued on the Write request 
packet queue for later processing. 

Applications may not see write requests complete in the order that 
they were received by the device driver. The order of the data trans- 
mitted due to the Write requests will reflect the order that the 
requests were received by the device driver. 
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The data from the Write requests are placed in the device driver 
transmit queue. The number of characters written are considered to 
be the number of characters given to the transmit hardware and not 
the number of characters placed in the device driver transmit queue. 
Because of time-out processing, it is possible that the total number of 
Write characters requested will not be transmitted. This is not con- 
sidered an error. The request is completed when completes or when 
the amount of data requested is given to the transmit hardware (but 
not actually transmitted at the physical RS232C interface). 

The different kinds of write time-out processing are discussed in the 
section on "States of the ASYNC Device Driver" on page 9-11. 

If infinite write time-out processing is enabled, then it is the responsi- 
bility of the application to monitor the status of the write requests. 
The application may have to issue an lOCtI to disable infinite write 
time-out processing to cause the write request to complete (without 
all the data being transmitted). If an application does not wish to 
check that all the data is given to the transmit hardware on each write 
request, the application can use the infinite time-out processing mode 
of the device driver to ensure that all the data has been given to the 
transmit hardware before the request completes. 

In order to increase the throughput (ratio of number of characters 
transmitted per second to the baud rate), the application should keep 
the write requests as large as possible. 
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DOS Mode Considerations / Restrictions 

DOS mode applications tliat go directly to the COM hardware or that 
use INT 14H are not supported. The 40: area is set to 0 by the device 
driver for those ports serviced by the device driver. 

Previous-level DOS device drivers that go directly to COMn hardware 
are not supported. 

The DOS 3.3 CTTY Utility is not supported. 

The AUX device name does not appear in the device header for the 
ASYNC device driver. AUX does not correspond to C0M1. 

We strongly recommend applications using a serial printer from the 
DOS mode spool print data to the print spooler through the appro- 
priate LPT handles. 

The only support to COMn in the DOS mode is through the file 
system. Family API restrictions should be consulted for the subset of 
Category 1 iOCtIs that are supported in the DOS mode. 

COM support in the DOS mode is incompatible with COM support in 
DOS. COM support in DOS 3.3 is half duplex through INT 14H. COM 
support in OS/2 has the following attributes: 

• Full duplex 

• Interrupt driven 

• Sophisticated time-out processing 

• Many different control modes of the modem control signals 

• Logical flow control capabilities 

• No application knowledge of state of modem control signals and 
data flow on a character basis. 
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The device driver mal<es no attempt to restrict or mold the function of 
file system requests because they may have come from the DOS 
mode. To achieve the full capabilities of the file system access to 
COM, the application needs access to the full range of Category 1 
lOCtls. The design and externals of the ASYNC device driver are 
based on the requirements of new OS/2 mode applications that use 
the RS232-C port of the system. 

If the DOS mode is concurrently sharing a COM port with OS/2 mode 
(not recommended), then care must be taken not to switch away from 
the DOS mode while the DOS mode application has requests out- 
standing in the file system. Switching away from the DOS mode, 
while file system requests are outstanding, could cause the device 
driver not to process certain file system requests that are outstanding 
(for a given port). 

Refer to the SETCOM40 command in the IBM Operating System/2™ 
User Reference. 

Performance 

The achievable performance is very sensitive to its environment. The 
type and amount of other system activity will determine the achiev- 
able performance. On PS/2 the number of COM ports or other 
devices on the same interrupt level will significantly affect the achiev- 
able performance level. 

Trying to receive data at too high a baud rate could cause hardware 
overrun errors or receive queue overrun errors. Receive queue 
overrun errors are easily solved by adjusting the communications 
protocol to the size of the device driver receive queue. 

Trying to transmit data at too high a baud rate also could cause the 
performance of the OS/2 system to be lessened severely. 

Configuration 

The baud rate can be set with the MODE command or with an lOCtl. 
The baud rate should not be set to values which may cause receive 
overruns or adverse OS/2 system performance effects. 
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Pointer Draw (Screen) Device Driver 



The Mouse Pointer Draw (Screen) device driver draws tlie system 
default and user-supplied mouse pointer images on the screen at 
interrupt time. 

In the OS/2 mode, the pointer draw device driver (POINTDD.SYS) pro- 
vides two levels of display mode support: 

• Full draw support. 

• Disabled state support. 

Full Draw Support 

Full draw support includes the full pointer drawing capabilities of a 
pointer device driver. The following display modes are supported at 
this level: 

• Text only 

modes 0, 1, 2, 3 and their + and * variations, 
mode 7 and its + variation. 

These modes are always accepted by the CheckModeProtect func- 
tion. 

If a mode other than one of the above is set using VioSetMode and 
pointer drawing is not disabled, the pointer device driver will report 
an error to the mouse device driver causing the mouse device driver 
to shut down. When the Mouse device driver is shut down, the API is 
active but no interrupt data can be returned. In this case, a status 
flag is set and is available using MouGetDevStatus. 
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Disabled State Support 



Disabled State support is available when the pointer draw functions 
have been disabled by the MouSetDevStatus function. When this 
occurs, an extended set of display modes is supported by the 
CheckModeProtect function. These display modes are: 

• Text modes 

modes 0, 1, 2, 3 and their + and * variations, 
mode 7 and its + variation. 

• Graphics modes 

modes 4, 5, 6, 7, D, E, F, 10, 11, 12, and 13. 

• The IBM Personal System/2™ Display Adapter advanced function 
modes. 

In the disabled state, no pointer drawing is performed by the pointer 
draw device driver. Instead, the application is expected to perform 
the pointer draw functions. 

While in this state, subsequent MouSetDevStatus function calls to re- 
enabie the pointer drawing will continue to be bypassed until 
VioSetMode resets the screen mode to one of the supported modes. 

In the DOS mode, the pointer draw device driver (POINTDD.SYS) pro- 
vides full pointer draw functions for the following modes: 

• Text modes 

modes 0, 1, 2, 3, and their + and * variations, 
mode 7 and its + variation. 

• Graphics modes 

modes 4, 5, 6. D, E, F, and 10. 
All other modes will cause the mouse device driver to shut down. 
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Mouse Device Driver 



Mouse Device Overview 

This section describes tlie standard mouse device driver interface 
provided by OS/2 for both DOS mode and OS/2 mode applications. 

IMouse Devices Supported: Mouse device drivers are supported in 
botli DOS mode and OS/2 mode for the following devices: 

• Microsoft®^ Bus (parallel) Mouse for IBM Personal Computers 
(part number 037-099, lOOppI) 

• Microsoft® Bus (parallel) Mouse for IBM Personal Computers 
(part number 037-199, 200ppl) 

• Microsoft® Mouse (serial) for IBM Personal Computers (part 
number 039-099, lOOppi) 

• Microsoft® Mouse (serial) for IBM Personal Computers (part 
number 039-199, 200ppi) 

• PC Mouse™2 (serial) by Mouse Systems (part number 
900120-214, lOOppI) 

• Visi On™3 Mouse (serial) (part number 69910-1011, lOOppi) 

• Microsoft® Mouse (inPort) for IBM Personal Computers (part 
number 037-299, 200ppl) 

• PS/2 Mouse (In-Processor) for IBM Personal System/2™ Com- 
puters (part number 6450350, 200ppi) 

While the OS/2 mouse device drivers support both DOS mode and 
OS/2 mode applications, the means by which DOS mode applications 
access the mouse device differs from OS/2 mode application access. 

DOS mode applications must use the interrupt 33H (INT 33i-l) interface 
described later in this chapter. OS/2 mode applications must use the 



1 Microsoft is a registered trademark of Microsoft Corporation 

2 PC Mouse is a trademark of Metagraphics/Mouse Systems 

3 Visi On is a trademark of Vis! On Corporation 
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OS/2 mode MOUxxx API also described in this chapter and in Tech- 
nical Reference, Vol. 2. 

OS/2 mode applications may not use the INT 33H API nor may DOS 
mode applications use the MouXxx mouse interface. 

PS/2 Mouse: The PS/2 mouse is an "in-processor" mouse. It is not 
compatible with existing mouse devices. The PS/2 mouse requires 
its new device driver. The PS/2 mouse is supported for both the DOS 
mode and OS/2 mode applications but only on a PS/2 processor. The 
PS/2 mouse is not supported on the Personal Computer AT or Per- 
sonal Computer XT Model 286. 

The Personal Computer AT serial mouse attachment cards will not fit 
in the PS/2 chassis. However, the OS/2 mouse devices are supported 
on PS/2 by allowing the user to connect the mouse devices to the 
PS/2 serial port. The PS/2 mouse device driver implementation uti- 
lizes ABIOS Pointing Device ABIOS commands. 

OS/2 D/D Serial Mouse Interrupt Sharing: OS/2 Personal Computer 
AT Serial mice do not share interrupts. Mouse device drivers attempt 
to capture the COM line specified by the SERIAL keyword on the 
mouse device's DEVICE statement in the CONFIG.SYS file. If exclu- 
sive use is denied, mouse device driver installation will fail. The 
OS/2 PS/2 mouse device drivers are modified to allow interrupts to be 
shared with other ASYNC drivers. The request for interrupts is non- 
exclusive. 

On the PS/2, the mouse device drivers will always receive exclusive 
access to the requested I/O port. However, the mouse device driver 
will never receive exclusive access to the device interrupt. 

System Install ensures that mouse device driver initialization tal^es 
place prior to ASYNC device driver initialization. This allows the 
ASYNC device driver to determine that it is not responsible for ser- 
vicing that port. This will ensure that mouse device drivers will not 
be preempted from the COMx ports by the ASYNC device drivers. 

For PS/2, OS/2 Mouse device drivers utilize the ABIOS command 
"Return LID Parameters" to determine which interrupt level they are 
executing on. Under no circumstances can the Mouse Device drivers 
select a predetermined interrupt. 
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Mouse Screen Resolutions: The screen resolution is determined by 
eitlier system default or by the application's issuing an explicit 
VIoSetMode call In the OS/2 mode or an INT 10H, AH = 0 In the DOS 
mode or INT 10H, AH = 11 Character Font Generator Selections. 
When in DOS mode the virtual display resolution is used. The virtual 
display resolution depends on the display mode selected. The fol- 
lowing display modes are supported: 







Text 


Graphics 


Virtual (X,Y) 


Cell 


Mode 


Type 


Resolution 


Resolution 


Coordinates 


Size 


0 


BW Text 


40x25 


320 X 200 


640 X 200 


8x 8 


0 + 


BW Text 


40x25 


320 X 350 


640 X 200 


8x 14 


0* 


BW Text 


40x25 


360 X 400 


640 X 200 


9x 16 


1 


CO Text 


40x25 


320 X 200 


640 X 200 


8x 8 


1 + 


CO Text 


40x25 


320 X 350 


640 X 200 


8x 14 


1* 


CO Text 


40x25 


360 X 400 


640 X 200 


9x 16 


2 


BW Text 


80x25 


640 X 200 


640 X 200 


8x 8 


2 + 


BW Text 


80x25 


640 X 350 


640 X 200 


8x 14 


2* 


BW Text 


80x25 


720 X 400 


640 X 200 


9x 16 


3 


CO Text 


80x25 


640 X 200 


640 X 200 


8x 8 


3 + 


CO Text 


80x25 


640 X 350 


640 X 200 


8x 14 


3* 


CO Text 


80x25 


720 X 400 


640 X 200 


9x 16 


4 


Graphics 




320 X 200 


640 X 200 


2x 1 


6 


Graphics 




320 X 200 


640 X 200 


2x 1 


6 


Graphics 




640 X 200 


640 X 200 


1 X 1 


7 


Mono 


80x25 


720 X 350 


640 X 200 


9x 14 


7 + 


Mono 


80x25 


720 X 400 


640 X 200 


9x 16 


D 


Graphics 




320 X 200 


640 X 200 


2x1 


E 


Graphics 




640 X 200 


640 X 200 


1 X 1 


F 


Graphics 




640 X 350 


640 X 350 


1 X 1 


10 


Graphics 




640 X 350 


640 X 350 


1 X 1 



Mouse installation: Mouse support is installed at iPL (start-up) time. 
The mouse support may be tailored according to the user's needs. 
This is accomplished via use of the CONFIG.SYS file to define system 
mouse requirements. 

The following describes the CONFIG.SYS DEVICE = keywords avail- 
able to customize the mouse subsystem and related mouse device 
driver installation. 

• The SERIAL = keyword Is used to specify the communications 
port that a serial mouse device is connected to. 
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Note: Utilities support up to eight COM ports on PS/2 (C0M1 - 
C0M8) and up to two on Personal Computer AT (C0M1 and 
COM2). Device drivers support up to tliree on PS/2 (C0M1 - 
COM3) and up to two on Personal Computer AT (C0M1 and 
COM2). C0M1, COM2 and COM3 should be used for ASYNC. 

This keyword is not valid for nonserial mice, (Microsoft Bus 
Mouse, Microsoft InPort Mouse, and IBM PS/2 Mouse, for 
example). 

If this keyword is not present (for serial mice), the default used is 
C0M1. Otherwise, either C0M1 or COM2 must be specified for 
the Personal Computer AT or PS/2. COM3 through C0M8 may be 
specified for serial mice on a PS/2 only. 

• The QSIZE = keyword is used to specify the event queue length 
to be used for all OS/2 mode sessions. 

If this keyword is not present, a default of 10 (maximum queue 
elements) is used. If a queue length is specified, the keyword 
must be followed by a signed integer in the range: 

1 < = integer < = 100 

Each queue element occupies 10 bytes. Therefore, the default 
event queue size allocates 100 bytes of event queue buffer space 
per session. 

A maximum of 16 sessions is allowed to utilize mouse support at 
any one time. This is true even if the number of sessions speci- 
fied for the system Is greater than 16. If an attempt is made to 
open mouse support for more than 16 sessions, an error will 
occur. 

• The MODE= keyword, enables the user to specify whether the 
mouse support is required for DOS mode only, OS/2 mode only or 
both modes. 

The acceptable MODE= values are: 

B = Both DOS mode and OS/2 mode support 
P = OS/2 mode support only 
R = DOS mode support only 

The default for the MODE= option is Both. Consequently, if this 
MODE= option is not specified, both DOS mode and OS/2 mode 
device driver support will be loaded into the system. 
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For example, if the user specifies a CONFIG.SYS file with a 
DEVICE = mouseAOO.sys and none of the other parameters, the 
internal result would be as if the user had specified the following 
statement: 

DEVICE=mouseA00. sys , SERIAL=C0M1 ,MODE=b ,QSIZE=10 

Mouse Device Driver Packaging: The DOS mode and OS/2 mode 
device drivers are contained within the same executable modules. 
Each of the supported devices is supplied with a named device driver 
containing both DOS mode and OS/2 mode function. 

Personal Computer AT Mouse Device Drivers: The following drivers 
support the Personal Computer AT and Personal Computer XT Model 
286. (These are not to be used for PS/2 hardware.) 

• MOUSEAOO.SYS = PC Mouse by Mouse Systems - Serial (part 
number 900120-214) 

• MOUSEA01.SYS = Vis! On Mouse - Serial (part number 
69910-1011) 

• MOUSEA02.SYS = Microsoft Mouse for IBM Personal Computers 

- Serial (part numbers 039-099 and 039-199) 

• MOUSEA03.SYS = Microsoft Mouse for IBM Personal Computers 

- Parallel (part numbers 037-099 and 037-199) 

• MOUSEA04.SYS = Microsoft Mouse for IBM Personal Computers 

- InPort (part number 037-299) 

PS/2 Mouse Device Drivers: The following drivers support PS/2 
hardware: 

• MOUSEBOO.SYS = PC Mouse by Mouse Systems - Serial (part 
number 900120-214) 

• MOUSEB01.SYS = Visi On Mouse - Serial (part number 
69910-1011) 

• MOUSEB02.SYS = Microsoft Mouse for IBM Personal Computers 

- Serial (part numbers 039-099 and 039-199) 

• MOUSEB05.SYS = PS/2 In-Processor Mouse (part number 
6450350) 
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The system loads the entire module into storage during initialization. 
The mouse device driver examines the parameter on the MODE = 
keyword (if one exists) on the CONFIG.SYS, DEVICE = MOUSExx.SYS 
line specifying the mouse device driver to determine whether both 
modes of support are required. 

If OS/2 mode is not required, the storage occupied by the OS/2 mode- 
only portions of the mouse device driver support is removed from 
storage. 

Mouse Pointer Draw Implementation: Communication between both 
DOS mode and OS/2 mode mouse device drivers and the pointer 
draw screen device routine is conducted by way of a FAR call from 
the mouse driver to the entry point of the screen pointer draw routine. 

The setup required for the mouse device driver prior to issuing the 
call to the pointer draw routine is as follows: 

• Set DS:SI to point to the session data control blocl< described 
below. 

• Set the screenjunc field to indicated the desired function code. 

• Issue a FAR call to the screen pointer draw routine. The address 
to be called must be stored in the screen_entp field of the session 
data control block. 

When the mouse device driver calls the screen pointer draw routine, 
the draw routine must issue a CU to disable interrupts. The mouse 
device driver will have disabled the lOCtIs and the mouse device 
interrupts. These will be enabled by the mouse device driver after the 
pointer draw routine returns to it. 

All addresses to data obtained via a DevHlp_AllocPhys is stored in 
the control blocks in 32 bit physical address form. The pointer draw 
routine must convert these addresses to virtual format (selector:offset 
for OS/2 mode and segment:offset for DOS mode) with the 
DevHlp_PhysToVirt call. The resulting selector is temporary and will 
be valid for no rnore than 400 microseconds. If an interrupt occurs 
during the 400 microsecond span, the temporary selector becomes 
invalid. 

Consequently, the screen pointer draw routine must: 

• Disable interrupts using the CLI instruction 
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• Complete all operation within the 400 microsecond time limit 

• Reenable interrupts. 

It is possible for the screen pointer draw routine to do repetitively the 
following in order to bypass the 400 microsecond time limit: 

• Enable interrupts 

• Disable interrupts 

• Call DevHIp.PhysToVirt 

• Execute draw functions. 

However, interrupt time operations should be as limited in scope and 
duration as possible to reduce the impact on the remainder of the 
system. Therefore, all effort should be directed to completing the 
pointer draw operations as quickly as possible and without exceeding 
a single 400 microsecond Interval. 

The functions to be supported by the screen pointer draw routine are: 

• screen_func = 0 = DrawPointer (Bimodal) 

• screen_func = 1 = RemovePointer (Bimodal) 

• screenjunc = 2 = FreePointerMemory (Bimodal) 

• screenjunc = 3 = CheckModeProtect (OS/2 mode only) 

• screenjunc = 4 = CheckModeReal (DOS mode only) 

• screenjunc = 5 = GetPolnterMemory (Bimodal) 

The following chart outlines the interrupt state of the 8259 for the 
commands that may be executed with calls from the mouse device 
driver to the screen pointer draw routine. The chart also describes 
the execution modes from which the commands may be invoked. 



Function Type 

DrawPointer 

RemovePointer 

FreePointerMemory 

CheckModeProtect 

CheckModeReal 

GetPolnterMemory 



Interrupt Status 

Disabled @ 8259 Level 
Disabled @ 8259 Level 
Disabled @ 8259 Level 
Disabled @ 8259 Level 
Disabled @ 8259 Level 
Disabled @ 8259 Level 



Call Modes 

Interrupt, User, Kernel 
Interrupt, User, Kernel 
User, Kernel 
Kernel 
User 

User, Kernel 
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Details concerning each of tliese commands follow: 

• DrawPointer draws the current mouse pointer image if it is not 
within the area defined by the collision area definition fields and 
If it Is not already visible on the screen. 

• RemovePolnter removes the current mouse pointer image from 
the screen if it was visible. Before the call, an advisory param- 
eter (CX) is set as follows: 

CX = 0 The RemovePolnter call may not be immediately fol- 
lowed by a DrawPointer call. The Pointer device 
driver must consider such a call an unconditional 
request for pointer removal, and honor the remove 
pointer. 

CX = 1 The RemovePointer call will be Immediately followed 
by a DrawPointer call (that is, the pointer image is to 
be moved rather than removed). The Pointer device 
driver can consider this RemovePointer call as advi- 
sory. 

A Pointer device driver which examines the CX value may 
decide, if CX is 1, to defer removal of the pointer image until the 
DrawPointer call can be examined also. Depending on the 
sophistication of the pointer driver, this can provide more effi- 
cient image updating. However, the pointer driver may choose to 
ignore the advisory indication (CX = 1), in which case it must 
always remove the pointer Image. 

For the case where CX is 1 , it is guaranteed that for the given 
screen group, no other function call will be made to the pointer 
driver between the RemovePointer and the DrawPointer calls. 
However, there Is no guarantee that a function call for another 
screen group will not occur. Thus, the pointer driver making use 
of the advisory nature of RemovePointer must save pointer infor- 
mation on a per-screen-group basis. The Screen_Tble field can 
be used by the pointer driver to extend the per-screen-group 
information as needed. 

• FreePointerMemory can only be issued after a RemovePointer to 
free both the current pointer image buffer and its associated 
screen restore buffer. This call has no effect if the default pointer 
is the screen pointer. 
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• CheckModeProtect verifies the requested mode_data structure 
values as either supportable or unsupportable: 

- If the requested OS/2 mode screen mode is unsupportable, 
the mouse screen device driver will set an error code of 1 in 
the AX register and return. 

- If the requested mode is supportable, the function will set the 
control block mode data fields accordingly and set a valid 
return code of 0 in AX. In addition, the cell sizes (in the 
control block) for the new mode must be filled in. 

Mode_data is a 12 byte data structure pointed to by ES:DI. 
The mode_data structure Is defined below. 

• CheckModeReal verifies the requested mode_data structures 
values as either supportable or unsupportable as follows: 

- If the requested DOS mode screen mode is unsupportable, 
the mouse screen device driver will set an error code of 1 in 
the AX register and return 

- If the requested mode is supportable, the mouse screen 
device driver will set the control block mode data fields and 
set a valid return code of 0 in AX. In addition, the cell sizes 
(in the control block) for the new mode are filled in. 

Real_mode_data is a 3-byte data structure pointed to by 
ES:DI. The ReaLmode.data structure is defined below. 

• GetPointerMemory will only be issued after a FreePointerMemory 
in order that the mouse screen device driver may allocate 
memory for both the new pointer image buffer and its associated 
screen restore buffer. 

This function receives the address of the pointer definition control 
block in ES:Di. The pointer definition control block contains two 
addresses. They are: 

- The address of the pointer image buffer 

- The address of the pointer definition record 

The pointer definition record is defined below. 

If the pointer image data is incomplete, unsupportable, or this 
function can't get the memory required to copy the pointer image 
buffer, an error code of 1 is returned in the AX register. 

If the image data Is OK, this function: 
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- Copies the pointer definition record data into the control 
block 

- Copies the pointer image buffer, and 

- Sets a valid return code of 0 In the AX register. 

In order to maximize pointer image draw performance, there are 
restrictions on defining graphics pointer images. These limitations 
follow: 

• Graphics modes utilizing the 320x200 resolution require pointer 
images be defined with 4 pixels per byte. 

• Graphics modes utilizing the 640x200 resolution require pointer 
images be defined with 8 pixels per byte. 

In other words, graphics pointer images must be defined in byte- 
width multiples. Non-byte width definitions will be accepted by the 
pointer draw routine but may result In unexpected pointer Images 
appearing on the display screen. 

The pointer image does not need to be drawn on the screen by the 
pointer draw routine. It is feasible for the pointer draw routine to dis- 
patch a process at level 2 or 3 and have that process affect pointer 
draw operations. 

This approach may be of particular use to those subsystems and 
Environment Managers which conduct a large number of screen or 
processing functions for each interrupt. 

Mouse Device Driver - Default Pointers: The default pointer images 
supplied by the system are a default text pointer for OS/2 mode only 
and a default text and graphics pointer for DOS mode. Two images 
are supplied; Default text image, and Default graphics image. 

The default text image is defined as a one-word reverse video block 
In which the screen character remains visible. 

The default graphics image is defined as an upward pointing arrow 
leaning toward the right side of the screen. 

The same graphics pointer Image Is used for both medium (320x200) 
and high resolution (640x200) graphics modes. Medium resolution 
pointers may contain up to four colors. High resolution pointers are 
limited to two colors, black and white. 
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The bit definitions of tiie default pointer images foilow: 



DefText Struct ;defaul 

ANDmsk DW 0FFFFH 

XORmsk DW 07700H 
DefText Ends 



t text pointer 

; default text AND mask 

; default text XOR mask 



DefGrph Struct ; default grapliics pointer 

ANDmask DB IIIUIIIB.IIOOOOIIB :default graphics ptr 

DB llllllllB.lOOOOOllB ;AND mask 

DB llllllUB.OOOOOOllB 

DB lllllllOB.OOOOOOllB 

DB 11111100B,00000011B 

DB lllllOOOB.QOOOOGllB 

DB llllGQOQB.OOQQQOllB 

DB IIIOOOOOB.OOQQQQIIB 

DB IIOOOOOOB.OOOOOOIIB 

DB lOOOOOOOB.OOOOOOllB 

DB lOOOOGOOB.OOOOOOllB 

DB llllOOOOB.OOOGOOllB 

DB llllGGQGB.GGGGGGllB 

DB 11106G00B,G0111111B 

DB lllOOGGOB.GlllllllB 

DB lllGGGQGB.GlllllllB 
XORmask DB OGGGGOO0B,GOOGGOOGB :XOR mask 

DB GGGGGGG0B,GGG1GOGGB 

DB GGOOOGOGB.OGllOGGGB 

DB OOGOOGOOB.GlllOOOOB 

DB GGGQGGGGB.llllGQGGB 

DB QQGGOGGlB.llllQGGGB 

DB GGGQGGllB.llllGQGQB 

DB G0G0G111B.111160GGB 

DB OOOOllllB.llllOOGGB 

DB QGGlllllB.llllQQGGB 

DB QGGGQQ01B.1111GQ0GB 

DB QQQQGQIIB.GGGIGQQQB 

DB GG00GD11B.GG0GG60GB 

DB OOGOOllGB.OGQGOOOOB 

DB 000G011GB,G0G00000B 

DB OOOOQOOOB.GOOOOOOOB 



DefGrph Ends 
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For all system-supported modes, TotLength is equal to: 

• 4 for text modes. 

• 64 for graphic modes. 

Mouse Device Driver - Control Blocks: internai mouse pointer control 
blocks are described below. Tliese structures are used by both the 
mouse device DOS mode and OS/2 mode drivers and the screen 
pointer draw routines. 

Key to Notes 

M = Mouse device driver access only 

P = Pointer draw device driver access only 

BM = Both peek - only mouse device driver may modify 

BP = Both peek - only pointer device driver may modify 

MON = Mouse device driver + monitor 



Mouse Session Data Area Template (118 Byte structure) 

This control block is passed during calls from the mouse 
device driver to the pointer draw device driver. 

DS : SI points to this control block 



scrgp_data STRUC 

; Session control data sub- table (next 40 Bytes) 



Rowscal e_Fact 


DW 


? 


M 


row coordinate scale factor 


Col seal e_Fact 


DW 


? 


M 


column coordinate scale factor 


Row_Remain 


DW 


? 


M 


row coordinate move remainder 


Col .Remain 


DW 


? 


> M 


column coordinate move remainder 


D_Status 


DW 


? 


M 


device status flags 


E_Mask 


DW 


? 


M 


enabled event table 


Hdl e_Cntr 


DW 


? 


M 


# of active device handles 


E_Queue 


DW 


? 


M 


event queue DS starting offset 


Eq_Head 


DW 


? 


M 


event queue head displacement 


Eq_Tail 


DW 


? 


> M 


event queue tail displacement 


Eq_PID 


DW 


? 


M 


PID blocked on event queue 


Eq_Size 


DB 


7 


M 


# of used elements in queue 


Chain_Size 


DB 


7 


M 


# of monitors in chain 


Chain_Hdle 


DW 


7 


M 


monitor chain handle 
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Screen_Entp DD ? ; M screen driver entry point address 



Screen_Tbl e DD ? 
Screen_Func DW ? 
Screen DS DD ? 



P 0 to screen drivers data table 

B screen driver function code 

BM screen driver data segment address 

stored as offset/selector or 

stored as offset/segment 



Monitor chain output buffer (next 14 Bytes) 



MB_Len 


DW 


? 


MFlags 


DW 


? 


EMask 


DW 


? 


Time 


DD 


? 


Row_Pos 


DW 


? 


Col Pos 


DW 


? 



MON Monitor Buffer Length (14 bytes) 

MON monitor flags 

MON event occurrence mask value 

MON event time stamp (Time of Day in milliseconds 

MON current pointer row coordinates 

MON current pointer column coordinates 



Display information data sub-table (next 64 Bytes) 
Display Mode fields 



Length 


DW 


7 


BP 


len of display mode fields (bytes) 


Mtype 


DB 


7 


BP 


mono text/color text/color graphic 


Color 


DB 


7 


BP 


# of color bits (graphic type only) 


TCol_Res 


DW 


? 


BP 


column resolution (text) 


TRow_Res 


DW 


? 


BP 


row resolution (text) 


GCol_Res 


DW 


7 


BP 


column resolution (graphics) 


GRow_Res 


DW 


7 


BP 


row resolution (graphics) 


Col_Cen_Size 


DW 


7 


BP 


graphics col res/ text col res 


Row_Cell_Size 


DW 


7 


BP 


graphics row res/ text row res 


Mouse Pointer 


fields 




Ptr_Flags 


DW 


? 

• 


P 


pointer image visible/hidden 


Ptr_Height 


DW 


? 


P 


height of ptr image (resolution units) 


Ptr_Width 


DW 


? 
• 


P 


width of ptr image (resolution units) 


Ptr_Row_Pos 


DW 


? 


BM 


current ptr row coord position 


Ptr_Col_Pos 


DW 


? 


BM 


current ptr col coord position 


Ptr_Row_Ref 


DW 


? 


P 


row coord ptr shape reference pxl 


Ptr_Col_Ref 


DW 


? 


P 


col coord ptr shape reference pxl 


Ptr_Image_Buf 


DD 


? 


P 


physical addr to ptr image bufr 


Ptr_Buf_Len 


DW 


? 


P 


pointer image buffer len (bytes) 


Ptr_Imagelen 


DW 


? 


P 


pointer image length (bytes) 


Ptr_Imageoff 


DW 


? 


P 


pointer image offset (bytes) 


Ptr_Linelen 


DW 


? 


P 


pointer image line length 


Ptr_Skiplen 


DW 


7 


P 


pointer image skip length 


Tot_Li nel en 


DW 


7 


P 


pointer total line length 


Ptr_Savstart 


DW 


7 


, P 


pointer save start pointer 
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Ptr_Savend DW ? ; P pointer save end pointer 
Ptr_Savstartodd DW ?; P pointer save start odd pointer 
Ptr_Savendodd DW ? ; P pointer save end odd pointer 



Collision Area fields 

Area_Flags DW ? ; BM area flags (area defined/undefined) 

Area_Row_Pos DW ? ; BM area starting row coord position 

Area_Col_Pos DW ? ; BM area starting col coord position 

Area_Row_End DW ? ; BM area ending row coord position 

Area_Col_End DW ? ; BM area ending col coord position 
scrgp_data ENDS 



Pointer Definition Record Template 
(12 byte structure) 

Following is used to pass data about the pointer image 
during the MouSetPtrShape call. 

Ptr_def_cb structure points to this control block. 



ptr_template STRUC 



bufj en 


DD 




; BM 


ptr shape buffer byte length 


wi dth 


DW 




: BM 


pointer width shape dimension 


height 


DW 


? 


; BM 


pointer height shape dimension 


col_hot 


DW 


? 


; BM 


ptr col coord hot spot pixel 


row_hot 


DW 


? 


: BM 


ptr row coord hot spot pixel 



ptr_template ENDS 



Mode Data Record Template 
(12 byte structure for OS/2 mode) 

Following is used to pass setmode data only. After setmode 
a copy of this is in the equivalent fields in the first 
control block. 

ES : DI points to this control block 



Mode_Data STRUC 

len DW ? ; BM Length of this data structure 

m_type DB ? ; BM Display Mode type value 

m_color DB ? ; BM Number of color bits 

tcol res DW ? ; BM text column resolution 
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trow_res DW ? ; BM text row resolution 

gcol_res DW ? ; BM graphics column resolution 

grow_res DW ? ; BM graphics row resolution 

Mode_Data ENDS 



GetPointerMemory Data Structure 

Used to pass pointer image @ and associated control block 
from mouse dd to pointer draw dd on MouSetPtrShape only. 

ES : DI points to this control block 



ptr_def_cb STRUC 

addrl DD ? ; BM addr to ptr definition record 
addr2 DD ? ; BM addr to ptr image buffer 

ptr_def_cb ENDS 



CheckModeReal Data Structure 

The structure's first (3) fields (R_Mode, Ex_Rows, 
Ex_Points), are copied from the DOS mode BIOS data 
area. Indicates that mode to which the DOS mode is 
about to be set by an INT lOH, AH=0 (setmode) call, or is 
about to be changed by INT 10H, AH=11, AL=lx (character 
generator calls). The Pointer Draw Device Driver will 
return to the Mouse Device Driver the new Display Mode's 
virtual coordinate maximum grid values via the virt_rows and 
virt_cols structure fields. 

ES : DI points to this control block 



Real_Mode_Data STRUC ; For real mode support 

r_mode DB ? ; BM Standard Disp Mode, CGA 

ex_rows DB ? ; BM Number of Rows, EGA 

ex_points DW ? ; BM Standard Disp Mode, EGA 

virt_rows DW ? ; BP New Disp Mode Virt Coord Row Max 

virt_cols DW ? ; BP New Disp Mode Virt Coord Col Max 

Real_Mode_Data ENDS 
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OS/2 Mode Mouse Support 

This section describes tlie standard OS/2 mouse device support for 
OS/2 mode applications. 



Overview: Mouse device drivers have characteristics which are quite 
different from most other devices. They are read-only devices which 
provide data at approximately 30 events per second. The data is 
structured, that is, it will arrive as a packet of data containing abso- 
lute screen location, button up/down and other information. 

The OS/2 mode mouse driver model described In this section is 
designed to provide a basic, machine-Independent, high-performance 
interface. Applications and Environment Managers may use this 
interface to obtain mouse device services. 

The Base Mouse Subsystem (BMS) is a dynamic linl< module which 
executes on level 3 (application level). The BMS receives all MouXxx 
calls (as a common entry point) and passes those calls to the appro- 
priate handler. One handler per session is allowed. 

Normally, the system supplied default handler is the session's mouse 
handler. However, Environment Managers, OEM, and custom mouse 
device drivers may find it necessary to intercept MouXxx calls for 
various reasons. A particular custom handler may service many dif- 
ferent sessions, provided it uses MouRegister with each of those ses- 
sions. 

Pointer image updating Is executed by the mouse device driver uti- 
lizing functions supplied by the display device drivers. The pointer 
updating occurs at interrupt time, ensuring that the pointer shape 
moves smoothly and promptly across the screen. The MouXxx API 
contains three commands which allow the application to: 

• Set the pointer shape 

• Reserve a collision area where the pointer must not be drawn 

• Free a collision area to the pointer device. 

The responsibilities of the mouse driver have been well separated 
from those of a screen driver. Pointer updating functions call the 
display device drivers rather than attempting to draw the pointer 
image directly. This maintains independence between the mouse 
and display devices. It does require that custom display device 
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drivers conform to the pointer device driver interface to allow the 
pointer shape to be drawn and also requires that the application syn- 
chronize display access. 

Pointer Draw Installation: The mouse pointer image update design 
allows the update routine to be installed with the video subsystem. 
Custom and OEM video subsystems, which allow display modes not 
supported by the base video subsystem, may implement interrupt- 
time screen pointer image updating by providing screen image draw 
routines for execution by the pointer device driver. 

Screen pointer draw routines are called by the mouse pointer device 
driver at interrupt time. The screen pointer draw routines are 
installed as character device drivers at start time. 

The necessary steps for installing a screen pointer image draw 
routine are outlined below: 

• Pointer draw routines are Installed at IPL time by including them 
on a DEVICE = keyword In the CONFIG.SYS file as named char- 
acter device drivers. No special mechanism is needed. The 
default pointer draw device driver file named POINTDD.SYS is 
needed. 

• The display (screen) = lOCtI (category 3, Function 72H) must be 
supported by the named pointer draw device driver. This lOCtI 
allows the mouse subsystem router/handler to query the pointer 
draw device driver for the entry (far call) address. 

• When an application uses MouOpen to a mouse handle, the 
mouse subsystem handler/router will inspect the stack to deter- 
mine if the call specified a non-system pointer draw device driver 
name. 

— If the pointer Is 0, the mouse subsystem will use the default 
(system supplied) device driver. This means that the session 
is restricted to display modes 0 through 7. 

- If the pointer was not 0, the mouse subsystem will follow the 
pointer to get the ASCilZ name of the pointer draw device 
driver. 

• The mouse subsystem handler/router will OPEN the pointer draw 
character device driver using DosOpen. Using the device handle 
returned by the OPEN, the handler/ router will then issue the cate- 
gory 3, Function 72H screen lOCtI to get the entry address 
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(selector : offset) of the pointer draw device driver. The mouse 
device driver will issue FAR calls to this entry address when the 
mouse has a pointer manipulation request. 

• The mouse subsystem handler/router will then do a DosOpen to 
the mouse device driver. The return value from this call will be a 
standard OS/2 device handle. 

• The mouse subsystem handier/router will use the DosOpen 
device handle to pass the entry address of the pointer draw 
routine to the mouse device driver. This is done by using the cat- 
egory 7, Function 5AH mouse lOCtI addressed to the mouse 
device driver's DOS handle. 

• The mouse device driver will call the pointer draw routine with 
each request without their being linked prior to start time. 
Linkage will be established (via the lOCtIs) for each pointer draw 
device driver specified by a MouOpen. 

• There may be only one pointer draw routine (driver) for each 
session. 

• This mechanism applies to OS/2 mode only. 

Handler/Router: There are three aspects to an OS/2 mouse 
handler/router: 

• MouXxx API to allow applications to avoid the specifics of the low 
level lOCtI interface 

• Circular buffers to receive events 

• Pointer management interface. 

The driver is installed as a character device, with the name 
"MOUSExxx.SYS." The MouOpen function call initializes the device 
(sets initial coordinates, checks for mouse presence). 

The MouXxx interface allows the caller to obtain information about 
the current state of the mouse, set parameters, allow the application 
to determine which events are to be passed into the device circular 
buffer, and others. 

The circular I/O buffer is a high-efficiency buffer shared by all client 
applications in the session and the mouse device driver. There is 
only one queue per session, no matter how many applications within 
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the session are utilizing the mouse device. The driver uses this inter- 
face to provide "events." The caller can specify what constitutes an 
event. Examples of events are pressing buttons and moving a 
mouse. 

Events are time-stamped so that a higher-level interface library 
package can provide such features as pressing the mouse button 
twice. 

Coordinates: Coordinates are mouse event's "absolute" position rel- 
ative to the top left corner (0,0) of the display screen. This means 
that the units in which the mouse position Is reported depends on the 
display mode in which the session is executing. There are two dif- 
ferent possibilities: 

• In TEXT mode, pointer position is reported in CHARACTER units. 

• In GRAPHICS mode, pointer position is reported in PIXELS. 

By supplying pointer coordinates as offsets to absolute screen posi- 
tion, higher level library support for translating data into an absolute 
coordinates may no longer be necessary. 

For those systems that wish to operate in terms of "relative" mouse 
movement (mickey) displacements, the MouSetDevStatus call allows 
the library support or the application to set the mouse device driver 
to return mickey movements and not screen coordinates. 

Motion: The unit of motion for a mouse is known as a "mickey." This 
is similar to the pixel, the unit of addressability on a screen. 

The OS/2 mouse driver provides calls to determine the number of 
units of motion per centimeter, so that an application, window 
manager or other package can relate motion to a physical screen. 

Mou Xxx and lOCtI Calls: The mouse lOCtI is category 7. Applica- 
tions should not concern themselves with the details of the mouse 
lOCtI interface. Instead, the OS/2 Mouse device driver should be 
accessed by applications via the MouXxx API. Only Environment 
Managers and custom mouse device drivers need be aware of the 
lOCti interface. 
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All mouse device driver lOCtI functions have an application-level 
MOU API equivalent function. The lOCtI function codes and their 
MOU API equivalents are as follows: 



lOCtI Fen 


mOU API Function 


Function Performed 


IOMR_NB 


MouGetNumButtons 


Get # of mouse buttons 


IOMR_MC 


MouGetNumMlckeys 


Get # of mickeys/centimeter 


IOMR_GS 


MouGetDevStatus 


Get device status flags 


IUMW_Uo 


Mouoetuevotatus 


Set device status flags 


lOMR_QS 


MouGetNumQueEl 


Get event queue status 


IUMH_nU 


MouReadEventQue 


Read event queue contents 


IOMR_Qr 


MouuetocaiePact 


Get current scaling factors 


IOMW_SS 


MouSetScaieFact 


Set new scaling factors 


IUMn_vjM 


MouGetEventMask 


Get current event mask 


IUMW_tM 


MoubetbventMasK 


Set new event mask 


N/A 


MouOpen 


Open mouse support 


N/A 


MouClose 


Close mouse support 


N/A 


MouRegister 


Install a mouse subsystem 


N/A 


MouDeRegister 


Deinstall a mouse subsystem 


N/A 


MoulnitReal 


Initialize DOS mode driver 


lOMW.SP 


MouSetPtrShape 


Assign new pointer shape 


IOMW_GP 


MouGetPtrShape 


Assign new pointer shape 


IOMW_DP 


MouDrawPtr 


Unmark collision area 


IOMW_RP 


MouRemovePtr 


Mark collision area 



OS/2 Mode Mouse API 



Please refer to Technical Reference, Vol. 2 for a discussion of the 
function calls dealing with Mouse OS/2 mode APIs. A summary of 
Mouse OS/2 mode API descriptions follows: 



MouRegister 
MouDeRegister 
MoulnitReal 
MouOpen 

MouClose 

MouDrawPtr 
MouRemovePtr 
MouFiushOue 
MouGetDevStatus 



Register mouse subsystem 
Deregister mouse subsystem 
Initialize DOS mode pointer draw 
Opens the mouse device for the current 
session 

Closes the mouse device for the current 
session. 

Release screen area for device driver use 

Reserve screen area for application use 

Flush mouse event queue 

Query current pointing device driver status 

flags 
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MouGetEventMask 

MouGetNumButtons 
MouGetNumM ickeys 
MouGetNumQueEl 

MouGetPtrPos 

MouGetPtrShape 

MouGetScaleFact 

MouReadEventQue 

MouSetDevStatus 

MouSetEventMask 

MouSetPtrPos 
MouSetPtrShape 
MouSetScaleFacI 
MouSynch 



Query current pointing device one-word event 
mask 

Query number of buttons 
Query number of mickeys per centimeter 
Query current status for tlie pointing device 
event queue 

Query current pointer position 

Query pointer shape and size 

Query scale factors for tlie current pointing 

device 

Read tlie pointing device event queue 
Set device status flags 

Assign new event mask to the current pointing 
device 

Set current pointer position 

Set pointer shape and size 

Set scale factors for the current pointing device 

Synchronize (serialize) access to the mouse 

device driver 



The MouOpen and MouClose commands are mapped by the Mouse 
Base Subsystem Router into the DosOpen and DosClose lOCtI com- 
mands, respectively. MouRegister and MouDeRegister are directed 
to the higher level Mouse Base Subsystem Router and do not trans- 
late down to the lOCtI device driver level. 



The Base Mouse Subsystem receives all MouXxx function calls. 
Function specific data is passed on the user's stack in the following 
format: 

Mouse Router return address 2 words <== Top of Stack 

Value of application DS reg. 1 word 

Entry point return address 1 word 

Function code 1 word 

Application (caller) ret addr 2 words 

Function specific parameters 2-10 bytes depending on call 



Events: The mouse driver provides data to the user through the 
standard OS/2 asynchronous and parallel I/O interfaces described in 
other sections of this Chapter. 

Mouse events are placed in a circular I/O buffer. The conditions 
which generate an event are controllable through the event mask 
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feature and are available by way of the MouSetEventMask call or the 
equivalent mouse lOCtI command. 

Mouse events have the following format: 

WORD Event Mask 

DWORD time stamp in milliseconds 

WORD Row absolute / mickeys 

WORD Column absolute / mickeys 

These fields have the following meaning: 

Event Mask: This indicates which event(s) are in this record. See the 
MouGetEventMasl< call description in Technical Reference, Vol. 2 for 
details on the event mask bit definitions. 

Time: This is a time stamp for the event. It is provided so that higher 
level interface packages can provide features like two mouse button 
presses with selective timing, and so that mouse and keyboard 
monitor events can be synchronized. The time value is the number of 
milliseconds since the last IPL. 

Row and Column / Mickeys: This may indicate either absolute posi- 
tion of the mouse pointer shaper relative to the top left corner of the 
display screen or mickey mouse movement. 

If reporting coordinates (the default), they will be in either pixel or 
character offsets, depending on whether the display mode for the 
session is graphics or text, respectively. 

The application must explicitly invoke reporting of mouse mickey 
units with the MouSetDevStatus call. In this case, events are 
reported in units of mouse movement. For rows, a negative number 
means movement toward the upper part of the screen. For columns, 
a negative number means movement toward the left part of the 
screen. 

Pointer: Maintenance of the pointer (shape and location) is per- 
formed by the mouse device driver. An application must provide the 
mouse driver with a pointer image that the driver will use to draw the 
pointer for that session. 

Applications utilizing mouse services need to ensure that the mouse 
device driver and the application do not attempt to update the screen 
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at the same location, at the same time. The MOD API provides three 
commands to accomplish these functions: 

• MouSetPtrShape 

• MouDrawPtr 

• MouRemovePtr 

It is the responsibility of the application to synchronize pointer oper- 
ations between itself and the pointer shape draw routine. 

Display Modes Supported: Graphic modes are only supported in the 
OS/2 mode if the application performs all drawing and moving of the 
pointer. The controlling application must first issue MouSetDevStatus 
and indicate no interrupt time pointer drawing, plus pointer move- 
ment reported in mickeys. Next, issue VioSetMode to the desired 
graphics modes. The graphic modes that are supported are 4, 5, 6, 
ODH, OEH, 010H, 011H, 012H, 013H and the 8514/A adapter Advanced 
Functions modes. 

DOS Mode Mouse Support 

This section describes the standard OS/2 mouse device support for 
DOS mode applications. 

Overview: DOS mode mouse support is based on the Microsoft INT 
33H support. 

DOS mode Mouse support preserves the INT 33H interface and is 
substantially compatible with existing Microsoft support. 

Pointer Draw Installation: DOS mode pointer draw installation is 
implemented via the MoulnitReal call. The shell issues the 
MoulnitReal call during shell initialization. The sequence of events is 

as follows: 

At SYSINIT (IPL) time, the shell (System Session Manager) issues 
MoulnitReal. 
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In order to establish addressability between the DOS mode mouse 
device driver and the DOS mode screen pointer draw routine: 

• The shell issues a MoulnitReal to open the system default Pointer 
Draw Device Driver. 

• The MoulnitReal issues category 3 (screen) lOCtI 72H to the DOS 
mode/OS/2 mode (shared) mode screen pointer draw device 
driver. This lOCtl will return the address of the pointer draw 
routine entry point. 

• The MoulnitReal will then issue category 7 (mouse) lOCtI 5BH to 
the DOS mode mouse device driver. This lOCtI passes the pointer 
draw address obtained from the preceding category 3, function 
72H lOCtI to the mouse device driver. 

• MoulnitReal will then return to the shell with a completion code 
indicating the result of the DOS mode mouse initialization 
process. 

Handler/Router: The Mouse Handler/Router is applicable only to 
OS/2 mode mouse support. In OS/2 mode, it directs operations 
among multiple sessions. In addition, it allows the MouXxx calls to 
be intercepted and synchronized between multiple processes in a 
session. This interception is done by an environment Manager, 
mouse subsystem, or a sophisticated application. 

DOS mode mouse support calls may be intercepted by hooking the 
INT 33H vector. While there are multiple OS/2 mode sessions 
allowed, there may not be more than one DOS mode session. Conse- 
quently, there Is no need for, and no support provided for, a DOS 
mode mouse handler/router. 

Coordinates: The OS/2 mode mouse reports its coordinate position in 
absolute displacement (characters or pixels) from the upper left 
corner of the screen. In a similar manner, DOS mode mouse support 
reports mouse coordinates relative to the upper left corner of the 
screen. 

In contrast, the DOS mode mouse support reports the position in 
virtual screen units. The virtual display coordinates are relative to 
the display mode. Refer to the table on page 9-36 for a list of the sup- 
ported display modes and their virtual display coordinates. 
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The OS/2 Mouse Device Drivers do not limit tlie virtual display coordi- 
nate settings. IHowever, if an application wislies to define tiie display 
with a larger virtual coordinate grid than the physical, it should also 
be prepared to perform the pointer image drawing because the OS/2 
virtual coordinate support will always map back to the virtual display 
space. The relative displacement of one unit will depend on the 
dimensions of the screen and the associated resolution for the mode 
setting on the display while the DOS mode is the foreground session. 

Motion: As with OS/2 mode mouse support, the unit of motion for a 
mouse is known as a "mickey". This is similar to the pixel, the unit of 
addressability on a screen. 

lOCtI Calls: There is only one lOCtI supported for the DOS mode 
mouse device driver. 

Portions of the mouse device driver are used by both the DOS mode 
and OS/2 mode device drivers. This shared portion supports the Cat- 
egory 7 (mouse), Function 5BH lOCtI for the DOS mode. This lOCtI is 
only used by the shell and then only at shell Initialization time. 

The OS/2 mod6 shell (System Session Manager) always exists in the 
OS/2 system. It is the shell (at shell initialization time) that calls for 
DOS mode mouse device initialization. The purpose of this shell call 
is to determine the entry point of the screen pointer draw device 
driver. It is this entry point which the mouse device driver will call on 
interrupts to have the pointer image updated for the DOS mode 
session. 

There are no other mouse lOCtIs in OS/2 that are supported by the 
DOS mode device driver. 

Events: The Microsoft INT 33H DOS mode mouse API is designed to 
detect and report "changes" in the state of the mouse. Consequently, 
the mouse support reports events such as: 

• Button Press data 

• Button Release data 

• Button Number 

• Mouse movement 
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Pointer: The DOS mode mouse API supports application pointer 
image setting. Two commands are provided to enable the application 
to modify the DOS mode pointer shape. They are: 

• Set Text Pointer Shape 

• Set Graphics Pointer Shape 

The first command is used while the display is in text modes. The 
second command is used while the display is in graphics modes. 

Display Modes Supported: Ail text modes are supported (0, 1, 2, 3 
and 7). Graphic modes 4, 5, 6, ODH, OEH, OFH and 010H are also sup- 
ported. 

Mouse Monitors 

Some applications need to view mouse device events as they arrive 
from the device driver. These applications may wish to consume 
some of the mouse events, or they may wish to replace some mouse 
events with one or more other mouse events. This is made possible 
by the "mouse monitor" function. 

The mouse device driver supports device monitors. The device 
driver passes information to the monitor in pacl<ets consisting of a 
word of monitor flags plus the standard mouse device driver event 
buffer. The paclcet format is as described below: 

WORD <00> — Monitor Flags — open, close, etc. 

WORD <02> -- Event mask (see MouGetEventMask for definitions) 

DWORD <04> -- Time stamp in milliseconds 

WORD <08> -- Absolute horizontal (x or row) screen position 

WORD <DA> — Absolute vertical (y or column) screen position 

The following DevHIp monitor control functions are used by the OS/2 
Mouse Device drivers to implement mouse monitors: 

• MonitorCreate 

• Register 

• Deregister 

• MonWrite 

• MonFlush 
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The OS/2 Mouse Device Driver uses the DevHIp monitor control func- 
tions for the following situations: 

MonltorCreate 

Creates a monitor chain for each OS/2 session, supported by the 
system, when the Mouse Device Driver receives and processes the 
system's INIT request. 

Removes each support session's monitor chain when a DEINSTALL 
request is received and processed. 

Register 

Add a monitor to a monitor chain for the current session when a reg- 
ister request is received and processed. 

The size of the mouse device driver's data buffer is 16 bytes. This Is 
the value to be used in calculating the sizes of the input/output 
buffers required for the DosMonReg call. 

Dereglster 

Remove a monitor from the current session's monitor chain when a 
dereglster request is received and processed. 

MonWrite 

Provide the current session's monitor chain event data at Interrupt 
time. 

IMonFiush 

Flush ail data from session's monitor chain. 

For additional information concerning device monitor function, see 
"Device Monitor Services" on page 6-32. 
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DOS Mode INT 33H Mouse API 



Please refer to Technical Reference, Vol. 2 for a discussion of the 
function calls dealing with Mouse OS/2 mode APIs. OS/2 supports a 
subset of the Microsoft DOS INT 33H mouse API. Refer to the table on 
page 9-36 for the display modes supported. 

The Microsoft INT 33H mouse API is available to only those applica- 
tions executing in the DOS mode. OS/2 mode applications must use 
the MOUxxx mouse device interface. 

The Mouse Device Driver provides DOS mode applications with an 
INT 33H interface to the pointing device hardware. The DOS mode 
support is not equivalent to the OS/2 OS/2 mode support instead, it 
preserves the Microsoft INT 33H mouse interface. 

The DOS mode Mouse does not support: 

• Device handles 

• Monitor chains 

• lOCtI direct function access. 

• MOU API function calls. 

All DOS mode mouse functions are accessed on the software INT 33H 
interface. When a software interrupt 33H is detected, a DOS mode 
Mouse Handler Routine is invoked. All function relevant information 
is supplied by the caller in the following seven registers: 

• AX 

• BX 

• OX 

• DX 

• SI 

• ES 

• Dl 

There are two states for the DOS mode Mouse support: 

• The OS/2 Mouse Device Driver is loaded into the operating 
system. When this state is active, all DOS mode Mouse functions 
listed in this section are available for user support. 

• The OS/2 Mouse Device Driver processes a Delnstallation 
request. In this state the DOS mode Mouse support is limited to 
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INT 33H, Function call 0. This is also true if an 
invalid/unsupported display mode was set. 

Mouse Device Driver Interfaces/Requirements: To get DOS mode 
mouse support, use MODE =R or MODE = B on the DEVICE = state- 
ment of CONFIG.SYS. 

Mouse Device Driver Button Definitions: The DOS mode button defi- 
nition depends on the number of buttons on the mouse device. 

Button definitions are used on functions 3, 5, 6, and 12. Button 
number assignments are as follows: 

Two-button mouse: 

Blt# Mouse Button 

1 Rightmost button 

0 Leftmost button 

Three-button mouse 

B/t# Mouse Button 

2 Center button 

1 Rightmost button 
0 Leftmost button 
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Mouse Device Driver Function Summary: The software INT 33H inter- 
face is provided only for DOS mode support. The INT 33H Mouse API 
provides the following functions: 



# 


Function Performed 


0 


Mouse Installed Flag and Reset 


1 


Show Mouse Pointer 


2 


Hide Mouse Pointer 


3 


Get Mouse Pointer Position & Button Status 


4 


Set Mouse Pointer Position 


5 


Get Button Press Information 


6 


Get Button Release Information 


7 


Set Min and Max Horizontal Position 


8 


Set Min and Max Vertical Position 


9 


Set Graphics Pointer Shape 


10 


Set Text Pointer Shape 


11 


Read Mouse Motion Counters 


12 


Set User-Defined Subroutine Input Mask 


13 


Light Pen Emulation Mode ON 


14 


Light Pen Emulation Mode OFF 


15 


Set Mickey/Pixel Ratio 


16 


Conditional OFF 


19 


Set Double Speed Threshold 


20 


Swap User-defined Subroutine 


21 


Query Save Mouse State Storage Requirements 


22 


Save Mouse Driver State 


23 


Restore Mouse Driver State 
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The function number and the function specific parameters are passed 
to the Mouse Device Driver in the four general purpose registers and 
the SI, Dl and ES registers. 

• The AX register is always used to contain the requested function 
number. 

• The BX, CX, and DX registers are used as needed for function- 
specific input parameters. 

• SI and Dl are used for function call 16. 

• ES is used for function calls 9 and 12. 

On return from a software interrupt 33H function call, the general 
purpose registers contain return codes and/or mouse requested data 
Items. The registers used are function-specific and detailed under 
each Individual call description. 

All input parameters are checked on function calls requiring parame- 
ters. 

If an INT 33H function call is issued when the Mouse 
Hardware/Software is not properly initialized, the call will return an 
error code of 0 In AX. 

The INT 33H Interface Is based on the concept of a virtual display 
screen coordinates. All coordinates are input/output relative to a 
default range of rows and columns. The default virtual range is 
required for the OS/2 Mouse Device Driver to perform the pointer 
image tracking on the display. However, an application Is not 
stopped from altering the virtual display coordinate limits through the 
INT 33H Interface. If an application alters virtual display coordinate 
grids to be greater than the physical display resolution, the pointer 
tracking will be unpredictable and all virtual coordinates read from 
the INT 33H interface may be Inaccurate. This Is properly support- 
able if the application which set the virtual coordinate ranges also 
assumes responsibility of pointer image drawing. The application 
can assume the INT 33H motion counters will not be affected and 
therefore Is a stable source of pointer Image motion data. 

The mouse device driver maps the physical display resolution to the 
virtual display screen coordinate system independent of the physical 
display mode. 
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INT 33H-0 Installed Flag and Reset 

Purpose Determines if the DOS mode Mouse device is present. 

If the appropriate mouse device hardware and software are 
available, this function will return a value of -1 in the AX reg- 
ister. In addition, this call will set/reset all of the software 
tracking mechanisms used by the other DOS mode mouse 
function calls to their default values. 

If the mouse hardware and/or software is not available for 
interaction, or if the video mode is not supported, this call 
will return a value of 0 in AX. 

Input Parameters: 

AX = function code of 0 
BX = not used 
CX = not used 
DX = not used 

Return codes/data values: 

If mouse support is not available, then 
AX = 0 

If mouse support is installed then 
BX = -1 

else (mouse support is available) 
AX = -1 

BX = number of mouse device buttons supported. 

The following table defines the default function values set 
when Mouse support is available (AX = -1): 

Function Default value 

Mouse pointer position Screen center 

Pointer redraw flag -1, Pointer hidden 

Graphics pointer image Mouse default image 

Text pointer image Reverse video 

Interrupt call mask All O's, no routine in use 

Light pen emulation mode Enabled 

Mickey/pixel ratio (horizontal) 8 to 8 

Mickey/pixel ratio (vertical) 16 to 8 

Min/Max ptr position (horizontal) Display/mode dependent 

Min/Max ptr position (vertical) Display/mode dependent 
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INT33H-1 Show Pointer 



Purpose Requests that the mouse device driver draw the pointer 
image and update the pointer redraw flag. 

This function determines if the mouse pointer image is 
already visible (pointer redraw flag = 0). If the pointer 
image is already visible, this function is a no-op. 

If the pointer redraw flag is not 0, this call increments the 
pointer redraw flag. After the pointer redraw flag is incre- 
mented, it is checked again to see if it is equal to 0. 

If the redraw flag was incremented to 0, the pointer image is 
redrawn on the display screen. 

If the internal cursor flag is already 0, this function has no 
effect. 

This function also clears conditional off (function 16) values. 
Input Parameters: 



AX = function code of 1 



BX = not used 
CX = not used 
DX = not used 



Return codes/data values: 



AX 
BX 
CX 
DX 



Unchanged 
Unchanged 
Unchanged 
Unchanged 
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INT33H-2 Hide Pointer 



Purpose Requests the mouse device driver to liide the pointer image 
and update the pointer redraw flag. 

This function decrements the mouse pointer redraw flag. If 
the pointer image is already hidden, the call returns to the 
application. If the mouse pointer redraw flag was decre- 
mented to -1, then the pointer image is hidden. 

When the cursor is hidden, the mouse device driver con- 
tinues to track the motion of the pointer on the screen. It 
simply does not draw the pointer image on the display. 

This function is used to ensure that the pointer device driver 
will not interfere with data being written on the screen by 
application programs. 

This function always decrements the cursor flag regardless 
of its current value. 

Input Parameters: 



AX = function code of 2 



BX = not used 
CX = not used 
DX = not used 



Return codes/data values: 



AX 
BX 
CX 
DX 



Unchanged 
Unchanged 
Unchanged 
Unchanged 
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INT 33H-3 Get Position & Button Status 

Purpose Returns the current nnouse button status and pointer image 
screen coordinates ((columns, rows) or (x, y)). 

Input Parameters: 

AX = function code of 3 
BX = not used 
CX = not used 
DX = not used 

Return codes/data values: 

AX = Unchanged 

BX = mouse button status 

CX = horizontal (x or column) pointer coordinate 

DX = vertical (y or row) pointer coordinate 

The mouse button status value is a bit mask indicating which 
mouse button(s) are currently pressed/released. 

A SET bit is defined as a button being pressed. 

Blt# Value/meaning 
3-15 Reserved = 0 

For two button mouse 

Bit# Value/ meaning 
2 Reserved = 0 

1 Set if rightmost button pressed 

0 Set if leftmost button pressed 

For three button mouse 

Bit# Value/ meaning 

2 Set if center button pressed 

1 Set if rightmost button pressed 
0 Set if leftmost button pressed 

The pointer coordinates are relative to the range defined for 
the mouse under the virtual terminal concept. The ranges 
are display mode dependent. See "Mouse Screen 
Resolutions" on page 9-36 for a description of the virtual 
screen resolution by mode. 
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INT 33H-4 Set Pointer Position 



Purpose Assigns the mouse pointer image to a new screen location. 

If the coordinates are too large, or too small, the mouse 
pointer position is set to the maximum or minimum screen 
values, respectively. 

Input Parameters: 

AX = function code of 4 
BX = not used 

CX = new pointer horizontal coordinate 
DX = new pointer vertical coordinate 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 

INT 33H-5 Get Button Press Information 
Purpose Returns a specified button's status information. 
Button status information consists of: 

• Up/down state of all buttons 

• A button press counter value 

• The last button press screen position coordinates 

The button press counter contains the number of times the 
requested button was pressed since the last time this call 
was issued. 

The button press counter is reset to 0 by this call. There is 
no overflow checking performed for the button press 
counter(s) when they are updated. 

The button press screen position coordinates are always 
reported in a virtual display mode value. 

The pointer coordinates are relative to the range defined for 
the mouse under the virtual terminal concept. The ranges 
are display mode dependent. See "Mouse Screen 
Resolutions" on page 9-36 for a description of the virtual 
screen resolution by mode. The values follow: 
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Input Parameters: 

AX = function code of 5 

BX = button status requested 

0 = leftmost button 

1 = rightmost button 

2 = center button 
CX = not used 

DX = not used 

Return codes/data values: 



AX = 


Bit-mapped as follows: 


Bim 


Meaning 


0 


= 0 If leftmost button is UP, 1 if down 


1 


= 0 If rightmost button Is UP, 1 If down 


2 


= 0 If center button is UP, 1 if down 


3-15 


= Not used 


BX 


= Button counter value 


CX 


= Last button press horizontal coordinate position 


DX 


= Last button press vertical coordinate position 



This function uses AX to return a value. If the Input param- 
eter in BX is illegal, then the output registers are returned 
as: 



AX = 0 
BX = 0 
CX = 0 
DX = 0 

INT 33H-6 Get Button Release Information 
Purpose Returns a specified button's status Information. 
Button status information consists of: 

• up/down state of all buttons 

• a button release counter value 

• the last button release screen position coordinates. 

The button release counter will contain the number of times 
the requested button was released since the last time this 
call was issued. 
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The button release screen position coordinates are always 
reported in a virtual display mode value. 

The pointer coordinates are relative to the range defined for 
the mouse under the virtual terminal concept. The ranges 
are display mode dependent. See "Mouse Screen 
Resolutions" on page 9-36 for a description of the virtual 
screen resolution by mode. The returned values are: 

Input Parameters: 

AX = function code of 6 

BX = button status requested 

0 = leftmost button 

1 = rightmost button 

2 = center button 
CX = not used 

DX = not used 

Return codes/data values: 



AX = 


Bit-mapped as follows: 


e/f# 


Meaning 


0 


= 0 If leftmost button is UP, 1 If down 


1 


= 0 If rightmost button is UP, 1 if down 


2 


= 0 If center button is UP, 1 if down 


3-15 


= Not used 


BX 


= Button counter value 


CX 


= Last button press horizontal coordinate position 


DX 


= Last button press vertical coordinate position 



This function uses AX to return a value. If the input param- 
eter in BX is illegal, then the input registers are returned 
as: 



AX = 0 
BX = 0 
CX = 0 
DX = 0 
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INT 33H-7 Set Min & Max Horiz Position 

Purpose Assigns virtual screen minimum and maximum horizontal 
coordinate positions. 

By defining virtual screen horizontal minimum and 
maximum coordinates, the pointer image is limited to a 
subset of the physical display horizontal movement area. 

If the value is too small, the current minimum value is used. 
Values larger than the maximum, the physical display resol- 
ution, may be used but with unpredictable pointer image 
tracking results. 

If the maximum value is less than the minimum, then the two 
values are swapped. 

If the pointer image is outside of the area when the call is 
made, it is moved to just inside the area. 

Input Parameters: 

AX = function code of 7 
BX = not used 

CX = minimum virtual screen horizontal position 
DX = maximum virtual screen horizontal position 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
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INT 33H-8 Set Min & Max Vert Position 



Purpose Assigns virtual screen minimum and maximum vertical coor- 
dinate positions. 

By defining virtual screen vertical minimum and maximum 
coordinates, the pointer image is limited to a subset of the 
physical display vertical movement area. 

If the value is too small, the current minimum value is used. 
Values larger than the maximum, the physical display resol- 
ution, may be used but with unpredictable pointer image 
tracking results. 

If the maximum value is less than the minimum the two 
values are swapped. 

If the pointer image is outside of the area when the call is 
made, it is moved to just inside the area. 

Input Parameters: 



AX = function code of 8 
BX = not used 

CX = minimum virtual screen vertical position 
DX = maximum virtual screen vertical position 



Return codes/data values: 



AX 
BX 
CX 
DX 



Unchanged 
Unchanged 
Unchanged 
Unchanged 
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INT 33H-9 Set Graphic Pointer Blocic 

Purpose Assigns a new graphics mouse pointer image. 

Tills function defines tlie sliape, color and iiot spot of tlie 
mouse pointer when the display Is in graphics mode. 

The following pointer image information must be provided: 

• New pointer Image horizontal hot spot coordinate 

• IMew pointer image vertical hot spot coordinate 

• Pointer to the new pointer image buffer 

The hot spot coordinates are pixel value indices relative to 
the upper left corner of the pointer. The relative hot spot 
coordinates must be In the range of +/- 16. 

The pointer image buffer must have a length of 64 bytes. 
The pointer image buffer is logically divided Into two bit 
level masks: 

• The first 32 bytes define the screen mask. The screen 
mask determines whether the pointer pixels are part of 
the shape or background. 

• the last 32 bytes define the pointer mask. The pointer 
mask determines how the pixels under the pointer con- 
tribute to the color of the pointer. 

The pointer draw routine first logically AMDs the screen 
mask with the 256 bits of data that define pixels under the 
pointer. Then it logically XORs the pointer mask with the 
result of the AND operation. 

In modes 6, ODH, OEH, OFH and 010H each screen bit 
defines the color of a single pixel. Thus, one bit In the 
screen mask and one bit in the pointer mask define the 
pixel's color when the pointer is over It. 

In modes 4 and 5, each pair of screen bits defines the color 
of a single pixel. Consequently, a pair of bits In the screen 
mask and a pair in the pointer mask define a pixel's color. 

Input Parameters: 

AX = function code of 9 

BX = pointer hot spot (horizontal position) 

CX = pointer hot spot (vertical position) 
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DX = address of screen and pointer masks 
ES = segment of screen and pointer masks 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
ES = Unchanged 

INT 33H-10 Set Text Pointer 

Purpose Defines a text (character) pointer image. 

Input Parameters: 

AX = Function code of 10 
BX = pointer select 

0 selects the software text pointer 

1 selects the hardware cursor 

CX = Screen mask value/hardware cursor start scan line 
DX = Pointer mask value/hardware cursor stop scan line 

For the software text pointer, the masks (CX and DX) are 
bitmapped as follows: 

Bit# Meaning 

15 Blinking 

14-12 Background Color 

11 Intensity 

10-8 Foreground Color 

7-0 Character 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
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INT 33H-11 Read Mouse Motion Counters 



Purpose Returns the number of mickeys the mouse has moved hor- 
izontally and vertically since the last time this function was 
called. 

The returned value is between -32768 and 32767. 

A positive number indicates motion to the right for horizontal 
motion, and to the bottom for vertical motion. 

This call sets the counts to 0. Overflow is ignored. 

Input Parameters: 



AX = Function code of 1 1 



BX = Not used 
CX = Not used 
DX = Not used 



Return codes/data values: 



AX 
BX 
CX 
DX 



Unchanged 
Unchanged 
Horizontal count 
Vertical count 
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INT 33H-12 Set User-defined Subroutine 

Purpose Sets the call mask and subroutine address for the mouse 
hardware Interrupts. 

The mouse driver will call the designated subroutine If any 
of the mask conditions are met. 

To cause the subroutine to be invoked for a certain condi- 
tion, set the corresponding bit in the call mask to a 1. If the 
subroutine is not to be Invoked for a condition, the corre- 
sponding bit should be a 0. 

Input Parameters: 

AX = Function code of 12 

BX = Not used 

CX = Call mask 

DX = Offset of subroutine 

ES = Segment of subroutine 

The call mask Is a word value with the following bit map: 

B/(# Meaning 

15-7 Reserved (0) 

6 Center button released 

5 Center button pressed 

4 Rightmost button released 

3 Rightmost button pressed 

2 Leftmost button released 

1 Leftmost button pressed 

0 Pointer position changed 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
ES = Unchanged 

When the mouse driver calls the subroutine, it loads the fol- 
lowing values Into the general purpose registers: 

AX = Condition mask (similar to the call mask except a 

bit is set only If the condition has occurred.) 
BX = Button State 

CX = Pointer Coordinate (horizontal) 
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DX = Pointer Coordinate (vertical) 

SI = Last raw vertical mickey count read from mouse 

Dl = Last raw horizontal mickey count read from mouse 

Note: Because the DS register contains the mouse driver 
data segment, the user's subroutine must set It to its own 
data segment value. 

INT 33H-13 Light Pen Emulation On 

Purpose Instructs the mouse device driver to emulate a light pen. 

Calls to the PEN function In IBM Basic will return the pointer 
position at the last "pen down". 

The "pen down" state is created by pressing the leftmost 
and rightmost buttons at the same time. 

The "pen off the screen" state occurs when either button Is 
up. 

Input Parameters: 



AX = Function code of 13 



BX = Not used 
CX = Not used 
DX = Not used 



Return codes/data values: 



AX 
BX 
CX 
DX 



Unchanged 
Unchanged 
Unchanged 
Unchanged 



9-78 



INT 33H-14 Light Pen Emulation Off 



Purpose Disables the mouse device driver light pen emulation. 

Input Parameters: 

AX = Function code of 14 
BX = Not used 
CX = Not used 
DX = Not used 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
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INT 33H-15 Set Mickey/Pixel Ratio 

Purpose Sets the mickey-to-pixel ratio for iiorizontal and vertical 
mouse motion. 

The ratios specify the number of mickeys per eight pixels. 
The values must be in the range: 

1 <= value < = 32767 

The default horizontal ratio is 8 to 8. With this ratio, mouse 
travel to move the pointer Image completely across the 
screen horizontally depends on the mouse device being 
used. The following table describes the movement by 
device. 

The default vertical ratio is 16 mickeys to 8 pixels. With this 
ratio, mouse travel to move the pointer image completely 
across the screen vertically depends on the mouse device 
being used. The following table describes the movement by 
device: 



Manufacturer 


Mouse 


PPI 


Mouse 


Horiz 


Vert 




Part No 




Type 


Travel 


Travel 


Microsoft 


037-099 


100 


Bus 


6.4 in 


4.0 in 


Microsoft 


037-199 


200 


Bus 


3.2 in 


2.0 In 


Microsoft 


037-299 


200 


InPort 


3.2 in 


2.0 in 


Microsoft 


039-099 


100 


Serial 


6.4 in 


4.0 in 


Microsoft 


039-199 


200 


Serial 


3.2 in 


2.0 In 


Mouse Systems 


900120-214 


100 


Serial 


6.4 in 


4.0 in 


Visi On 


69910-1011 


100 


Serial 


6.4 in 


4.0 In 


PS/2 


6450350 


200 


In-Proc 


3.2 in 


2.0 in 



Input Parameters: 

AX = Function code of 15 
BX = Not used 

CX = Horizontal Mickey/Pixel Ratio 
DX = Vertical Mickey/Pixel Ratio 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
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INT 33H-16 Conditional Off 



Purpose Defines a region on tlie screen for updating. 

If the mouse pointer is in tlie defined region, or moves into 
it, this function will hide the defined region while it is being 
updated. After this function is called, function 1 must be 
called later to show the pointer again. 

This function is similar to function 2, but is intended for 
advanced applications that need quicker screen updates. 
Because of the number of parameters required, this function 
cannot be called from interpreted BASIC. 

Input Parameters: 



AX = Function code of 16 
BX = Not used 

CX = Left Column (x or width) screen coordinate 
DX = Upper Row (y or height) screen coordinate 
SI = Right Column (x or width) screen coordinate 
Dl = Lower Row (y or height) screen coordinate 



INT 33H-19 Set Dbl Speed Threshold 

Purpose Sets the threshold speed for doubling pointer motion on the 



screen. 

The default value is 128 mickeys per second. If the mouse 
moves faster than this number, pointer motion doubles in 
speed. 



Return codes/data values: 



AX 
BX 
CX 
DX 



Unchanged 
Unchanged 
Unchanged 
Unchanged 



Input Parameters: 



AX = Function code of 19 
BX = Not used 

CX = Not used 

DX = Threshold speed in mickeys/second 
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Return codes/data values: 



AX 
BX 
CX 
DX 



Unchanged 
Unchanged 
Unchanged 
Unchanged 



INT 33H-20 Swap User^defined Subroutine 

Purpose Sets the call mask and subroutine address for the mouse 
hardware interrupts and returns the previous values of the 
call mask and subroutine address. 

The mouse driver will call the designated subroutine if any 
of the mask conditions are met. 

To cause the subroutine to be invoked for a certain condi- 
tion, set the corresponding bit in the call mask to a 1. If the 
subroutine is not to be invoked for a condition, the corre- 
sponding bit should be a 0. 

Input Parameters: 

AX = Function code of 20 

BX = Not used 

CX = Call mask 

DX = Offset of subroutine 

ES = Segment of subroutine 

The call mask is a word value with the following bit map: 

B/t# Meaning 

16-7 Reserved (0) 

6 Center button released 

5 Center button pressed 

4 Rightmost button released 

3 Rightmost button pressed 

2 Leftmost button released 

1 Leftmost button pressed 

0 Pointer position changed 

Return codes/data values: 



AX = Unchanged 

BX = Unchanged 

CX = Previous call mask 

DX = Offset of previous subroutine 

ES = Segment of previous subroutine 
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When the mouse driver calls the subroutine, it loads the fol- 
lowing values into the general purpose registers: 

AX = Condition mask (Similar to the call mask except a bit 
is set only if the condition has occurred.) 

BX = Button State 

CX = Pointer Coordinate (horizontal) 

DX = Pointer Coordinate (vertical) 

SI = Last raw vertical mickey count read from mouse 

Dl = Last raw horizontal mickey count read from mouse. 

Note: Because the DS register contains the mouse driver 
data segment, the user's subroutine must set it to its own 
data segment value. 

Because this call occurs at interrupt time, it should process 
the information quickly and return. If it does not, interrupts 
could be lost. 
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INT 33H-21 Query Save Mouse State Storage 
Requirements 

Purpose Get the size of the buffer required to store the current state 
of the mouse driver. 

Input Parameters: 

AX = Function code of 21 
BX = Not used 

CX = Not used 
DX = Not used 

Return codes/data values: 

AX = Unchanged 

BX = Size of buffer required to store the mouse state 
CX = Unchanged 
DX = Unchanged 

INT 33H-22 Save Mouse Driver State 

Purpose Save the mouse driver state in a user buffer. 

This function moves the mouse driver data, required to 
restore the mouse driver state, into the user defined buffer. 
This function is used in conjunction with function 23 when 
the mouse driver state must be saved and later restored. 

Input Parameters: 

AX = Function code of 22 

BX = Not used 

CX = Not used 

DX = Offset of buffer 

ES = Segment of buffer 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
ES = Unchanged 
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INT 33H-23 Restore Mouse Driver State 



Purpose Restore the mouse driver state from a user buffer. 

This function restores mouse driver data previously saved 
by function 22 (Save Mouse Driver State). This function is 
used in conjunction with function 23 when the mouse driver 
state must be saved and later restored. 

Input Parameters: 

AX = Function code of 23 

BX = Not used 

CX = Not used 

DX = Offset of buffer 

ES = Segment of buffer 

Return codes/data values: 

AX = Unchanged 
BX = Unchanged 
CX = Unchanged 
DX = Unchanged 
ES = Unchanged 
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VDisk Device Driver 



OS/2 includes a Virtual Disk installable device driver. Tliis driver, 
called VDISK.SYS supports the command line configuration shown 
below. 

In CONFIG.SYS: 

clevice=[d:] [path]vdisk.sys [bbbb] [ssss] [dddd] 

bbbb The first numeric value, if present, is the disk size in kilo- 
bytes. The default is 64, the minimum value is 16. 

ssss The second numeric value, if present, is the sector size in 
bytes. The default is 128. Allowed values are 128, 256, 512, 
and 1024. 

dddd The third numeric value, if present, is the number of root 

directory entries. The default is 64, the minimum value is 2 
and the maximum value is 1024. 

VDISK adjusts the value of dddd to the nearest sector size 
boundary. For example, if you give a value of 25, and the 
sector size is 512 bytes, 25 is rounded up to 32, the next mul- 
tiple of 16, (there are 16 32-byte directory entries in 512 

bytes). 

Note: In the event that there is not enough memory to create the 
VDISK volume, VDISK will try to make a DOS volume of 16K size. 

The device driver VDISK.SYS calls the OS/2 memory manager to allo- 
cate its memory requirements. 

Note: The OS/2 file system cannot accept a root directory containing 
more than 255 sectors. For example, a 64K RAM disk with 128 byte 
sectors and 1024 directory entries requires 256 sectors. This should 
be considered by the user when setting these parameters. In the 
above example, the maximum number of directories the user should 
specify when using 128 byte sectors is 1020. 
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CLOCKS Device Driver 



OS/2 assumes that the CMOS real-time clock Is available In the 
system. The CLOCKS device defines and performs functions like any 
other character device except that it is identified by a bit in the attri- 
bute word. OS/2 uses this bit to identify the device driver, and there- 
fore, this device can take any name. The device has been named 
"CLOCKS" to avoid possible conflicts with any files named "CLOCK." 

OS/2 on the Personal Computer AT makes use of the clock/calendar 
chip for its clock ticks. This device is not available on other models 
of the PC family and is therefore not programmed by the DOS mode 
applications. When the DOS mode is in the foreground, the regular 
18.2 HZ clock ticks arrive and are intercepted and/or disposed of in a 
DOS 3.3 compatible manner. When the DOS mode is in the back- 
ground, the 18.2 HZ clock is masked off. The clock/calendar clock 
continues to run In both modes. 

The CLOCKS device itself - the driver that sets and returns time of 
day ~ is dual mode and services both modes. There is no reserva- 
tion of the device; the time can be set from either mode. 

The CLOCK device is unique because OS/2 reads or writes a 6-byte 
sequence which encodes the date and time. Writing to this device 
sets the date and time, and reading from It gets the date and time. 

The following diagram illustrates the binary time format used by the 
CLOCK device: 
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CLOCK Device Time Format 



Byte 0 Byte 1 


Byte 2 


Byte 3 


Byte 4 


Byte 5 


Days since 1-1-80 


Minutes 


Hours 


Sec/100 


Seconds 


Low-byte Hi-byte 











The CLOCKS device driver sets and maintains tlie following fields in 
the Global InfoSeg: 

TIME 

Time from 1-1-1970 in seconds 

Milliseconds 

Hours 

Minutes 

Seconds 

Hundredths 

Timer interval 

DATE 

Day 

Month 

Year 

Day of week 

The CLOCKS device driver ensures that the date, time from 1-1-70 in 
seconds, and time of day (hours, minutes, seconds) fields remain syn- 
chronized with the CMOS clock and that the hundredths of seconds 
field is correctly synchronized with the seconds field. 
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Console Device Drivers (Screen and Keyboard) 



In OS/2, the generic console device driver has been replaced by two 
independent device drivers: 

Screen or console output (SCR$) 
Keyboard input (KBD$). 

The KBD$ device driver supports the OS/2 interrupt-driven architec- 
ture. The SCR$ and KBD$ device drivers are part of the resident 
device driver set. 

Keyboard Device Driver KBD$ 

The keyboard device driver interfaces the physical keyboard to appli- 
cations through various levels of routines. 
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Keyboard System Structure 



LVL 2 or 3 



Mon 1 



- Mon 2 



LVLO 



K 










E 










Y 
B 
0 


HW ^ 


Interrupt 


(1) 


Interrupt 


Handler 




A 










R 










D 










Scan Code 


Scan Code 
Translation 


(1) 



Transaction 



KCB 



Xiate 
Table 



Code 
Control 



Page 
Block 



XIate 
Table 



XIate 
Table 



US/437 



CP 1 



CP 2 



LVLO 




0- 



Keyboard 
Input 
Buffer 
Handler 



KIB 



Read Char. 
Data Rec. 
lOCTL 



LVL 3 



KbdCharin 



: DATA FLOW 

: CONTROL FLOW 



APPLICATION 



Monitor 
Dispacher 



(1) 

Unless 

Monitors 

Registered 



(2) 



(3) 



9-90 



Note: 



(1) Is part of the device driver interrupt liandler 

(2) Is part of the device driver strategy routine 

(3) Is part of the base sub-system/router 

The device driver receives the make-and-breal< l<eystrol<e scan codes 
and performs one or more of the following operations: 

• Translates the scan code to an ASCII character 

• Recognizes the key as a special key and signals the appropriate 
routine for processing 

• Passes the key to the monitor dispatcher for further custom proc- 
essing by monitors 

• Places the key character data record into the appropriate ses- 
sion's keyboard input buffer. 

• Calls the following sub-system functions to support handles: 

KbdOpen - Create a new logical keyboard 
KbdClose - Delete a logical keyboard 
KbdGetFocus - Bind the real keyboard to the logical one 
KbdFreeFocus - Free the real to logical keyboard bind. 

The keyboard device driver supports code page switching. The fol- 
lowing is a result of this support: 

• Each handle may use one of two system-wide code pages. One 
is the current and the other may be swapped to. Each handle 
may also use the PC US 437 code page. 

• The code pages to use are defined in CONFIG.SYS with the 
CODEPAGE and DEVINFO commands. 

• The code pages are for one language only. Code pages for dif- 
ferent languages could result if default code pages are not 
accepted during execution of the KEYB command. This could 
occur when attempting to load translate tables in a nonsupported 
code page for that language. 

• The user is allowed, via the KEYB command, to change the lan- 
guage layout of the keyboard. 



9-91 



• The user may control, by the KbdSetCp sub-system function or 
the CHOP command, which of the two code pages is used in the 
handle for translation. 

• Two sub-system functions support code page switching: 

KbdSetCp - Set to an installed code page, load if necessary. 
KbdGetCp - Get the current in-use code page. 

• KbdSetCustXt - Adds a custom code page option 

• KbdXIate - Translates a scan code 

• KbdSetCp, KbdGetCp,and KbdXIate may be replaced in the sub- 
system by the use of the KbdRegister function. 

• The code page header contains the code page number, the lan- 
guage ID of the table, the language default table indicator, and 
the l<ey board type indicator. 

Keyboard Initialization 

Prior to CONFIG.SYS processing, the device driver and keyboard sub- 
system routines are loaded. As part of the device driver load, the 
keyboard initialization routine is executed. At this time level 0 
memory is allocated and initialized. This memory will contain the 
KCBs, KIB, code pages, and related control blocks. A KCB is created 
for each possible session; this KCB is referred to as the 'default' 
logical keyboard for that session and is initialized to use the default 
code page. 

At the end of CONFIG.SYS processing, after the CODEPAGE and 
DEVINFO statements have been processed, the code pages must be 
initialized. This Is done by calling KbdSetCp. 

Keyboard Run Time Operation 

When a session is started, a default logical keyboard will already 
exist. This keyboard is identified to the sub-system by a 0 handle. 
Any program may share the keyboard by using handle 0. 

If multiple programs use the default keyboard, they must coordinate 
their access to it. The default keyboard logically terminates when the 
session terminates. 
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If a program wants a logical keyboard separate from the default 
logical keyboard, it does a KbdOpen. This open creates a new logical 
keyboard, but does not make the physical to logical bond. As a result 
of an open, a handle unique within a process is returned to the caller 
which is later used to identify the logical keyboard. The handle own- 
ership is tied to the process; handles are not inherited. Use of 
KbdOpen does not prohibit the process from using the default key- 
board. 

To make the physical to logical bond, the process issues the 
KbdGetFocus, using the handle identifying the logical keyboard. 
Once the bond is made, the logical keyboard may receive keystrokes. 
Note that type-ahead keystrokes are not possible before the bond is 
made. The Keyboard API may only be used when the bond is made 
or with handle 0 when no other handle has the bond. 

The bond represents a foreground keyboard; one exists per session. 
This is either the default or a created logical keyboard. 

Breaking the bond is done with the KbdFreeFocus call. If other 
threads have a KbdGetFocus outstanding, the thread having the 
highest priority will get the bond. If there are no KbdGetFocus calls 
outstanding, the physical keyboard will revert to the default keyboard. 

A logical keyboard Is destroyed with a KbdClose. The close will do a 
free focus, flush buffer, and de-allocate the KCB and related memory. 
Close will be done by the process kill mechanism, if not done by the 
program. 

Keystroke Monitors 

Some applications need to view the raw keystrokes as they arrive 
from the keyboard at interrupt time. These applications may wish to 
consume, modify, or replace keystrokes. This is made possible by 
the keystroke monitor function. 

When the DosMonReg call is used with keyboard devices, the index 
indicates the session, from 0 to 15 (see DosGetlnfoSeg). -1 indicates 
the session of the calling thread. 

The size of the keyboard device driver's data buffer is 16 bytes. This 
is the value to be used in calculating the sizes of the input/output 
buffers required for the DosMonReg call. 
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The keyboard device driver supports device monitors. The keyboard 
device driver passes Its information to the monitors in packets which 
contain the following information: 

Keystroke Monitor Data Packet Definition 



MonFlagWord: 


Word 


C 


XIatedChar: 


Byte 


h 
a 


XIatedScan: 


Byte 


r 
D 


DBCS Status: 


Byte 


a 
t 


DBCS Shift 


Byte 


a 


Shift State: 


Word 


R 
e 


Milliseconds: 


DWord 


c 

0 

r 
d 






KbdDDFIagWord 


Word 



mionFiagWord Lower Byte: Monitor Dispatcher Flags 

Blt# Meaning 

7-3 RESERVED = 0 

Should be passed untouched on packets being passed on. 
Should be set to 0 on packets that are being inserted by a 
monitor. 

2 FLUSH 

This is a flush packet. No other information in the packet has 
meaning. Monitor should flush its internal buffers and pass 
the packet quickly. 

1 CLOSE 

Not used by keystroke monitors. 

0 OPEN 

Not used by keystroke monitors. 
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MonFlagWord Upper Byte: Original Scan code, as read from the hard- 
ware. If 0, this packet was inserted for other reasons, see 
"KbdDDFIagWord" on page 9-95. Monitors pass this field untouched. 
Monitors should put a 0 here if they insert a packet. 

CharData Record: Same as defined by the KbdCharIn function call in 
Technical Reference, Vol. 2. 

KbdDDFIagWord 

B/f# Meaning 

15,14 Available. 

These bits are available for communication between monitors. 
They are not used by the device driver in any way. The 
monitor applications coordinate the use of these flags. 

13-10 RESERVED = 0 

Monitors should pass these flags as is. They should set these 
flags to 0 in packets that they create. 

9 ACCENTED 

This key was translated using the previous key passed, which 
was an accent key (Refer to 10H ACCENT KEY on page 9-98). 
In the case where an accent key is pressed and the following 
key doesn't use the accent, a packet containing the accent 
character itself is first passed, with this bit set (and the scan 
code field of MonFlagWord, see above, would be 0, indicating 
a non-key-generated record). Then a valid packet containing 
that following keystroke is passed, without this bit set. 

8 MULTIMAKE 

The translation process sees this scan code as a typeamatic 
repeat of a toggle key or a shift key. Because toggle and shift 
keys only change state on the first make after each key-break, 
no state information is changed (for example, the NUMLOCK 
toggle bit in the shift status word is not changed, even though 
this may be the NumLock key). If this key is a valid character, 
it will not go into the KIB once this bit is set. 

7 SECONDARY 

The scan code prior to the one in this packet was the SEC- 
ONDARY KEY PREFIX (see below). 
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6 KEY BREAK 

This record is generated by the release (the BREAK) of the key 
involved. 

5-0 Numeric field that tells the device driver that this is a key that 
requires action. The number in this field is filled in during the 
translation of the scan-code. The value here allows the device 
driver to act on keystrokes without regard for what scan codes 
the keyboard uses or character codes that the current trans- 
lation process may be using. The following values are cur- 
rently defined: 

VALUE FOR KEYS THAT ARE ALWAYS PLACED IN THE KIB 
0 - No special action. Always place in KIB. 

Values Acted On Prior to Passing Paclcet to IMonitors 

Except for the final keystroke of the REBOOT and DUMP key 
sequences, all of these values are passed on to the monitors. They 
will NOT be placed in the KIB. The XIatedChar and XIatedScan fields 
are undefined for these values: 

Scan Code Meaning 

01H ACK 

This scan code was a keyboard acknowledge. Personal Com- 
puter AT attached keyboards would set this value on a FAH 
scan code. 

02H SECONDARY KEY PREFIX 

This scan code was a prefix scan code generated by the 
Enhanced Keyboard, indicating that the next scan code coming 
is one of the secondary keys that exists on that keyboard. 
Usually set on a EOH scan code or a hex E1 scan code. 

03H KBD OVERRUN 

This scan code was an over-run indication from the keyboard. 
On a Personal Computer AT attached keyboard, this value 
would be set on a FFH scan code. 

04H RESEND 

This scan code was a "resend" request from the keyboard. On 
a Personal Computer AT attached keyboard this value would 
be set on a FEH scan code. 
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05H REBOOT KEY 

This scan code is the key that completes the multi-key restart 
sequence. On a Personal Computer AT attached keyboard this 
value would be used when the Ctrl + Alt + Delete sequence is 
seen. 

06H DUMP KEY 

This scan code is Is the key that completes the multi-key Stand 
Alone Dump request sequence. On a Personal Computer AT 
attached keyboard, this value would be used on completion of 
the second consecutive press of Ctrl + Alt +NumLock without 
other keystrokes between the two presses. 

07H-0AH See "Values Acted On After Passing Packet To Monitors." 

OBH Invalid Accent Combination 

This scan code is one that follows an accent scan code, but the 
combination was not valid and neither key is put in the KIB. 

Note: This is set if the Canadian-French code pages are in 
use. 

OC-OFH RESERVED = 0 

(Will be treated as UNDEFINED, see entry 3FH.) 

Values Acted On After Passing Packet To Monitors 

Except where noted, these will be placed in the KIB when the device 
driver is in BINARY mode, but will not be placed in the KIB when the 
device driver is in ASCII mode. Also noted are those that never get 
placed in the KIB. 

Scan Code Meaning 

07H SHIFT KEY 

This scan code translated as a shift key and has affected the 
shift status fields of the CharData record but does not generate 
a defined character, so it will not be placed in the KIB. The 
XIatedChar field is undefined. 

08H PAUSE KEY 

This scan code was translated as the key sequence meaning 
PAUSE. On a Personal Computer AT attached keyboard, this 
value will be used when the Ctrl + NumLock sequence is seen. 
The key itself will not be placed In the KIB. 
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09H PSEUDO-PAUSE KEY 

This scan code is translated into tlie value that is treated as 
the PAUSE key when the device driver is in ASCII mode. On 
most keyboards this would be when the Ctrl + S combination is 
seen. The key itself will not be placed in the KIB. 

OAH WAKE-UP KEY 

This scan code is the key that follows a PAUSE KEY or 
PSEUDO-PAUSE KEY which will cause the pause state to be 
ended. The key itself will be not be placed in the KIB. 

10H ACCENT KEY 

This scan code was translated as a key to be used in trans- 
lating the NEXT key to come in. The packet containing this 
value is passed when the accent key is hit, but it is not put into 
the KIB (unless the ACCENTED bit is on). Refer to ACCENTED 
bit on page 9-95. The next key determines this decision. If the 
next key is one that can be accented, then it will be passed by 
itself, with the ACCENTED bit on. If that next key cannot be 
accented by this accent, then two packets are passed. The 
first contains the character to print for the accent itself, has 
this value (ACCENT KEY) and has the ACCENTED flag (which 
says it's okay to put it in the KIB). The second packet contains 
a regular translation of that following key. 

Note: The two packets get passed for every language except 
Canadian-French. See entry OBH. 

11H BREAK KEY 

This scan code was translated as the key sequence meaning 
BREAK. On the Personal Computer AT attached keyboard, this 
value will be used where the Ctrl + Break sequence is seen. 

12H PSEUDO-BREAK KEY 

This scan code is translated into the value that is treated as 
the BREAK key when the device driver is in ASCII mode. On 
most keyboards this would be when the Ctrl + C combination is 
seen. Note that the event generated by this key is separate 
from that generated by the BREAK KEY when in the binary 
mode. 

13H PRINT SCREEN KEY 

This scan code was translated as the key sequence meaning 
PRINT SCREEN. On a Personal Computer AT attached key- 
board, this value will be used where the Shift-PrtSc sequence 
is seen. 
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14H PRINT ECHO KEY 

This scan code was translated as the key sequence meaning 
PRINT ECHO. This value will be used where the Ctrl +PrtSc 
sequence is seen. 

15H PSEUDO-PRINT ECHO KEY 

This scan code is translated into the value that is treated as 
the PRINT ECHO key when the device driver is in ASCII mode. 
On most keyboards this would show as the Ctrl + P combina- 
tion, 

16H PRINT-FLUSH KEY 

This scan code is translated into the key sequence Print-Flush. 
This value will be used where the Ctrl + Alt +PrtSc sequence is 
seen. 

17-2FH RESERVED = 0 

Will be treated as undefined, see entry 3FH. 

Values for Packets Not Generated by a Keystroke 
Scan Code Meaning 

30-37H RESERVED 

38-3EH RESERVED 

Will be treated as UNDEFINED, see entry 3FH. 

Value for Keys that the Translation Process does not Recognize 

Scan Code Meaning 

3FH UNDEFINED 

This scan code, or its combination with the current shift state, 
was not recognized in the translation process. 

Special Key Processing 

OS/2 examines each incoming keyboard character to determine if it 
should cause an asynchronous signal to be sent to some process (for 
example, Ctrl + C). The keyboard device driver responds to the fol- 
lowing keystrokes: 
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Keys 


Mode 


Event Signalled 
or Signal 
Handler Called 


Value 
Placed 
In KIB 


Ctrl + C 


Binary 


Nothina 

1 ^ v(l III Im 


03H 


Ctrl + C 


ASCII 


SIGINTR 

VrlKdliU III 


Nothina 

1 ^ wVtl III IM 


Ctrl + S 


Binary 


Nothina 

1 1^/11 III IM 


13H 


Ctrl + S 


ASCII 


event CtrlScrLk 


Nothina 

i ^ w«l II I IM 


Ctrl + P 


Binary 


Nothina 

I^Wil III 1^ 


10H 


Qlfl + p 


ASCII 


event Ctrl PrtSc 


Nothina 

Ivwil III IM 


Ctrl + Break 


Binary 


SIGBREAK 


OO'OOH 

W»WWI 1 


Ctrl + Break 


ASCII 


SIGINTR 

v^iwiiii III 


Nothina 

1 1^#fcl III Im 


Ctrl + NumLock 


Binary 


event CtrlScrLk 


Nothina 
i^wii ill 1^ 


Ctrl + NumLock 


ASCII 


event CtrlScrLk 


Nothina 

1 1 wbl III IM 


Ctrl + PrtSc 


Binary 


event Ctrl PrtSc 

WVWilfc %^bl II 1 LK^W 


00:72H 


Ctrl + PrtSc 


ASCII 


event Ctrl PrtSc 


Nothing 


PrtSc 


Binary 


event_ShftPrtSc 


Nothing 


PrtSc 


ASCII 


event_ShftPrtSc 


Nothing 



Notes: 

1. The value xxH represents the translated ASCII field in the char- 
acter data record. 

2. The value xx:yyH represents the translated ASCIktranslated scan 
code fields of the character data record. 

3. Ctrl + NumLock has no effect on an IBM Enhanced keyboard; the 
Pause key provides this function. 



9-100 



Key 



Meaning 



Hot Key 



Change sessions 



Ctrl+Alt+Del 



System IPL (Restart) 



Ctrl + Alt + NumLock Pressed twice means system dump 



PrtScr 



Print the current display screen (Shift + PrtScr 
on an IBM Personal Computer AT keyboard 
and Print Screen on an IBM Enhanced key- 
board) 



In addition to passing individual characters, the driver must specif- 
ically recognize the character (or character sequence, or other 
special action) that indicates the special signal or hot key to the 
session manager. When this event is recognized, the Send.Event 
helper function is invoked. 

Note that the system hot key is defined by lOCtI Category 4 Function 
561-i (Set Session Manager Hot Key). 

Compatibility Operations 

The DOS mode runs in its own session; the session mechanism keeps 
OS/2 mode programs from affecting the compatibility screen. When 
the DOS mode is no longer in the foreground, the old application is 
frozen, keeping it from affecting the OS/2 screen. The DOS mode 
has, in effect, an independent SCRN and KBD device driver in the 
form of a DOS mode CON driver. This driver is compatible with the 
ROM INT10 and INT16 entries and their associated low-memory data 
structures. 
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EGA.SYS Device Driver 



EGA.SYS is a device driver which provides support for the EGA Reg- 
ister Interface in the DOS mode. In the DOS mode, to support 
advanced graphics modes D, E, F and 10, the mouse pointer draw 
device driver must save/restore the EGA registers. Because the EGA 
registers are not readable, this can be done only if the application 
cooperates in setting the registers in the first place. Rather than 
doing I/O directly to the registers on the adapter, the application sets 
the registers through the EGA Register Interface. 

EGA Register Interface 

The EGA Register Interface Is a library of ten functions supported for 
DOS mode, advanced graphics (modes D, E, F, and 10) applications. 
These functions do the following: 

• Read from or write to one or more of the EGA write-only regis- 
ters. 

• Define default values for the EGA write-only registers, reset the 
EGA registers to these default values, or return the default 
values. 

• Check whether the EGA Register Interface Is present and, if so, 
return its version number. 

When your application uses the EGA Register Interface, OS/2 main- 
tains a backup copy of (shadows) how the EGA registers are set. 
Then, if the operator switches away from and later returns to your 
application, the registers will be restored properly. 

It is not necessary to use the EGA Register Interface to set the mode, 
color palette, or palette registers. Instead, use ROM BIOS function 
call INT 10H with AH = OOH, OBH, or 10H, respectively. 

How to Call the EGA Register Interface: To call EGA Register Inter- 
face functions from an assembly language program: 

1. Load the registers with the required parameter values. 

2. Execute software interrupt 10h. 

Values returned by the EGA Register Interface functions are placed in 
registers. 
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EGA Register Interface Restrictions: Functions not supported 

Multiple display pages in graphics modes are not supported. Fonts 
may be loaded (using ROM BIOS INT 10H with AH = 11H) into char- 
acter generator block 0 only. 

Attribute Controller Registers 

Before your application program uses the Attribute Controller regis- 
ters (I/O address 3C0H) in an extended interrupt 10H call, It must set 
the flip-flop that selects the address or data register so that it selects 
the address register (by doing an input from I/O port 3BAH or 3DAH). 
The flip-flop Is always reset to this state upon return from the 
extended Interrupt 10H call. 

Interrupt routines that access the attribute chip must also leave the 
flip-flop set to the address register upon return from the Interrupt. 
Note, if your application program sets the flip-flop so that it selects 
the Data register and expects the flip-flop to remain in this state, your 
application must disable interrupts between the time it sets the flip- 
flop to the Data register state and the last time the flip-flop is 
assumed to be in this state. 

Sequencer Memory Mode Register 

When the Sequencer Memory Mode register (I/O address 3C5H, data 
register 4) is accessed, the sequencer produces a glitch on the CAS 
lines that may cause problems with video random access memory. 
As a result, your application program cannot use the EGA Register 
Interface to read from or write to this register. Instead, use the fol- 
lowing procedure to safely alter this register: 

1. Disable interrupts. 

2. Set Synchronous Reset (bit 1) in the Sequencer Reset 
register to 0. 

3. Read/modify/write the Sequencer Memory Mode register. 

4. Set Synchronous Reset (bit 1) In the Sequencer Reset 
register to 1. 

5. Enable interrupts. 
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Input Status Registers 



Your application program cannot use the EGA Register Interface to 
read Input Status registers 0 (I/O address 3C2H) and 1 (I/O address 
3BAH or 3DAH). If your program must read these registers, It should 
do so directly. 

Graphics Controller Miscellaneous Register 

When the Graphics Controller Miscellaneous register (I/O address 
3GFH, data register 6) is accessed, a glitch on the CAS lines occurs 
that may cause problems with video random access memory. As a 
result, your application program should not use the EGA Register 
Interface to read from or write to this register. 

EGA Register Interface function F6 does not alter the state of the 
Graphics Controller Miscellaneous register. Instead, use the fol- 
lowing procedure to safely alter this register: 

1. Disable interrupts. 

2. Set Synchronous Reset (bit 1) in the Sequencer Reset register to 
0. 

3. Read/modify/write the Graphics Controller Miscellaneous reg- 
ister. 

4. Set Synchronous Reset (bit 1) in the Sequencer Reset register to 
1. 

5. Enable interrupts. 
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EGA Register Interface Functions: This section describes eacli EGA 
Register Interface function in detail. The following list shows these 
functions by function number: 

Number 



(Hex) 


r unction 


rU 


Read one register 


rl 


Write one register 


CO 


neau regisier range 


F3 


Write register range 


F4 


Read register set 


F5 


Write register set 


F6 


Revert to default registers 


F7 


Define default register table 


F8 


Read default register table 


FA 


Interrogate driver 



Note: Calls F9H, and FBIH through FFH are reserved. 

Each function description includes: 

• The parameters required to make the call (input) and the 
expected return values (output). 

• Any special considerations regarding the function. 

If the function description does not specify an input for a parameter, 
you don't need to supply a value for that parameter before making the 
call. If the function description does not specify an output value for a 
parameter, the parameter's value is the same before and after the 
call. 

Note: The EGA Register Interface does not check input values, so be 
sure that the values you load into the registers before making a call 
are correct. 
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Function FO - Read One Register 



Purpose Function FO reads data from a specified register on tiie EGA. 



AH = FOH 

BX = Pointer for pointer/data cliips: 

BH = 0 

BL = Pointer 

Ignored for single registers 

DX = Port nunnber: 

Pointer/data chips 

Oh: CRT Controller (3?4H) 

8h: Sequencer (3C4H) 

10h: Graphics Controljer (3CEH) 

18h: Attribute Controller (3C0H) 

Single registers 

20h: Miscellaneous Output register (3C2H) 
28h: Feature Control register (3?AH) 
30h: Graphics 1 Position register (3CCH) 
38h: Graphics 2 Position register (3CAH) 

? = B for monochrome modes or D for color modes 



AX: Restored 

BH: Restored 

BL: Data 

DX: Restored 

All other registers restored. 

Exampie: The following example saves the contents of the Sequencer 
Map Mask register in "myvalue:" 

myvalue db ? 



Input: 



Output: 



mov ah. Of Oh 
mov bx, 0002h 



fO = read one register 
bh « 0 / b1 = map mask 
index 

dx = sequencer 
get it! 
save it! 



mov dx, OOOSh 

int lOh 

mov myvalue, b1 
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The following example saves the contents of the Miscella- 
neous Output register in "myvalue": 



myvalue db 
mov 
mov 

int 
mov 



ah. Of Oh 
dx. 0020h 

IGh 

myvalue, bl 



fO = read one register 
dx = miscellaneous 
output register 
get it! 
save it! 
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Function PI - Write One Register 

Purpose Function F1 writes data to a specified register on tlie EGA. 

When your application program returns from a call to func- 
tion F1, tiie contents of registers BFH and DX are not 
restored. Your program must save and restore tliese regis- 
ters If desired. 



Input: 



Output: 



AH = F1h 

BL = Pointer for pointer/data ciiips 
Data for single registers, 

BH = Data for pointer/data cliips 
(ignored for single registers) 

DX = Port number: 

Pointer/data chips 

Oh: CRT Controller (3?4H) 

8h: Sequencer (3C4H) 

10h: Graphics Controller (3CEH) 

18h: Attribute Controller (3C0H) 

Single registers 



AX: 
BL: 
BH: 
DX: 



20h 
28h 
30h 
38h 



Miscellaneous Output register (3C2H) 
Feature Control register (3?AH) 
Graphics 1 Position register (3CCH) 
Graphics 2 Position register (3CAH) 



? = B for monochrome modes or D for color modes 



Restored 
Restored 
Not restored 
Not restored 



All other registers restored. 

Example: The following example writes the contents of "my value' 
into the CRT Controller Cursor Start register: 
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my value db 3h 



mov 


ah. Oflh 


; f 1 = 


write one register 


mov 


bh, myvalue 


; bh = 


data from myvalue 


mov 


bl , OOOah 


; bl = 


cursor start index 


mov 


dx. OOOOh 


; dx = 


crt controller 


int 


lOh 


; write it! 



The following example writes the contents of "myvalue" into 
the Feature Control register: 



myvalue db 2h 

mov ah, Oflh 

mov bl , myvalue 

mov dx, 0028h 

int lOh 



fl = write one register 
bl = data from myvalue 
dx = feature control register 
write it! 
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Function F2 - Read Register Range 

Purpose Function F2 reads data from a specified range of registers on 
the EGA. A range of registers is defined to be several regis- 
ters on a single chip that have consecutive indexes. This 
call is applicable for pointer/data chips. 

input: 

AH = F2h 

CH = Starting pointer value 

CL = Number of registers (must be > 1) 

DX = Port number: 

Oh: CRT Controller (3?4h) 

8h: Sequencer (3C4h) 

10h: Graphics Controller (3CEh) 

18h: Attribute Controller (SCOh) 

? = B for monochrome modes or D for color modes 

ES:BX = Points to table of one-byte entries (length = value 
in CL). On return, each entry is set to the contents of 
the corresponding register. 

Output: 



AX: 


Restored 


BX: 


Restored 


CX: 


Not restored 


DX: 


Restored 


ES: 


Restored 



All other registers restored. 

Example: The following example saves the contents of the Attribute 
Controller Palette registers in "paltable:" 
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paltable db 16 dup (?) 
tnov ax, ds 



mov es, ax 

mov bx. offset paltable 

mov ah, Of2h 

mov ex. OOlOh 



mov dx, 0018h 
int 10h 



assume paltable 1n 

data segment 
es = data segment 
es:bx = paltable 

address 

f2 = read register 
range 

ch = start index 
of 0 

cl = 16 registers 
to read 

dx = attribute 
control 1 er 
read them! 
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Function F3 - Write Register Range 

Purpose Function F3 writes data to a specified range of registers on 
tlie EGA. A range of registers is defined to be several regis- 
ters on a single chip that have consecutive indexes. This 
call is applicable for the pointer/data chips. 

input: 

AH = F3h 

CH = Starting pointer value 

CL = Number of registers (must be > 1) 

DX = Port number: 

Oh: CRT Controller (3?4h) 

8h: Sequencer (3C4h) 

10h: Graphics Controller (3CEh) 

18h: Attribute Controller (3C0h) 

? = B for monochrome modes or D for color modes 

ES:BX = Points to table of one-byte entries (length = value 
in CL). Each entry contains the value to be written to 
the corresponding register. 

Output: 

AX: Restored 
BX: Not restored 
CX: Not restored 
DX: Not restored 
ES: Restored 

All other registers restored 

Example: The following example writes the contents of "cursloc" into 
the CRT Controller Cursor Location High and Cursor 
Location Low registers. 
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cursloc db 01h, QQh 
mov ax, ds 



mov es, ax 

mov bx, offset cursloc 

mov ah, 0f3h 

mov cx, 0e02h 



mov dx, OOOOh 
int 10h 



cursor at page 

offset OlOGh 
assume cursloc in 

data segment 
es = data segment 
es:bx = cursloc 

address 

f3 = write register 
range 

ch = start index 
of 14 

cl = 2 registers to 
write 

dx = crt controller 
write them! 
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Function F4 - Read Register Set 



Purpose Function F4 reads data from a set of registers on the EGA. A 
set of registers is defined to be several registers tliat may or 
may not have consecutive indexes, and that may or may not 
be on the same chip. 

Input: 

AH = F4H 

CX = Number of registers (must be > 1) 

ES:BX = Points to table of records with each entry in this 
format: 

Bytes 1-2: Port number: 

Pointer/data chips 

Oh: CRT Controller (3?4H) 

8h: Sequencer (3C4H) 

lOh: Graphics Controller (3CEH) 

18h: Attribute Controller (3C0H) 

Single registers 

20h: Miscellaneous Output register (3C2H) 
28h: Feature Control register (3?AH) 
30h: Graphics 1 Position register (3CCH) 
38h: Graphics 2 Position register (3CAH) 

? = B for monochrome modes or D for color modes 

Byte 3: Pointer value (0 for single registers) 

Byte 4: EGA Register Interface fills In data read from reg- 
ister specified in bytes 1-3. 

Output: 

AX: Restored 
BX: Restored 
CX: Not restored 
ES: Restored 

All other registers restored 

Example: The following example saves the contents of the Miscella- 
neous Output register, Sequehcer Memory Mode register, 
and CRT Controller Mode Control register In "results:" 
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outvals dw 


0020h 




miscellaneous output 










regi ster 


db 


0 






0 for single registers 


db 


? 






returned value 


dw 


0008h 




sequencer 


db 


04h 






memory mode register 










i ndex 


db 


? 






returned value 


Hw 
uw 


OQOOh 






db 


17h 






mode control register 










index 


db 


? 






returned value 


results db 


3 dup (?) 






mov 


ax. 


ds 




, assume outvals in 










data segment 


mov 


es. 


ax 


; es = data segment 


mov 


bx. 


offset 


outvals ; es:bx = outvals 










; address 


mov 


ah. 


0f4h 




, f4 = read register set 


mov 


cx. 


3 




, number of entries in 










, outval s 


int 


lOh 






, get values into outvals 


mov 


si. 


3 




; move the returned 










; values from 


add 


si , 


offset 


outvals ; outvals 


mov 


di. 


offset 


results ; to results 


mov 


cx. 


3 


; 3 values to move 


loop: mov 


al. 


[si] 


; move one value from 


mov 


[di], al 




; outvals to results 


add 


si , 


4 




; skip to next source byte 


inc 


di 




; point to next destination 



; byte 



loop loop 



Function F5 - Write Register Set 

Purpose Function F5 writes data to a set of registers on the EGA. A 

set of registers is defined to be severai registers tliat may or 
may not liave consecutive indexes, and tliat may or may not 
be on the same chip. 

Input: 

AH = F5h 

CX = Number of registers (must be > 1) 

ES:BX = Points to table of values with each entry in this 
format: 

Bytes 1-2: Port number: 

Pointer/data chips 

Oh: CRT Controller (3?4H) 

8h: Sequencer (3C4H) 

10h: Graphics Controller (3CEH) 

18h: Attribute Controller (3C0H) 

Single registers 

20h: Miscellaneous Output register (3C2H) 
28h: Feature Control register (3?AH) 
30h: Graphics 1 Position register (3CCH) 
38h: Graphics 2 Position register (3CAH) 

? = B for monochrome modes or D for color modes 

Byte 3: Pointer value (0 for single registers) 

Byte 4: Data to be written to register specified in bytes 1-3 

Output: 

AX: Restored 
BX: Restored 
CX: Not restored 
ES: Restored 

All other registers restored 

Example: The following example writes the contents of "outvals" to 
the Miscellaneous Output register, Sequencer Memory 
Mode register, and CRT Controller Mode Control register: 
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outvals dw 



0020h ; miscellaneous output 

; register 

0 ; 0 for single registers 

Oa7h ; output value 

0O08h ; sequencer 

04h ; memory mode register index 

03h : output value 

0000h ; crt controller 

17h : mode control register index 

0a3h ; output value 

ax, ds ; assume outvals in 

; data segment 

es, ax ; es = data segment 

bx, offset outvals ; es:bx = outvals 

; address 

ah, 0f5h ; f5 = write register set 

ex. 3 ; number of entries in 

: outval s 

10h ; write the registers! 



db 
db 
dw 
db 
db 
dw 
db 
db 



mov 



mov 



mov 



mov 



mov 



int 



Function F6 - Revert to Default Registers 

Purpose Function F6 restores the default settings of any registers tliat 
your application program has changed through the EGA 
Register Interface. The default settings are defined in a call 
to function F7 (described in the next section). 

input: 

AH = F6h 

Output: 

Ail registers restored 

Exampie: The following example restores the default settings of the 
EGA registers: 



mov ah, 0f6h 



f6 = revert to default 
registers 
do it now! 



int 10h 
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Function F7 - Define Defauit Register Table 

Purpose Function F7 defines a table containing default values for any 
pointer/data chip or single register. If you define default 
values for a pointer/data chip, you must define them for all 
registers within that chip. 

input: 

AH = F7h 

DX = Port number: 

Pointer/data chips 

Oh: CRT Controller (3?4H) 

8h: Sequencer (3C4H) 

10h: Graphics Controller (3CEH) 

18h: Attribute Controller (3C0H) 

Single registers 

20h: Miscellaneous Output register (3C2H) 
28h: Feature Control register (3?AH) 
30h: Graphics 1 Position register (3CCH) 
38h: Graphics 2 Position register (3CAI-I) 

? = B for monochrome modes or D for color modes 

ES:BX = Points to table of one-byte entries. Each entry con- 
tains the default value for the corresponding register. 
The table must contain entries for all registers. 

Output: 

AX: Restored 
BX: Not restored 
DX: Not restored 
ES: Restored 

All other registers restored 

Example: The following example defines defauit values for the Attri- 
bute Controller: 
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attrdflt db OOh, Olh. G2h, G3h, 04h, 05h, 06h. 07h 

db lOh, llh, 12h. 13h. 14h. 15h. 16h, 17h 

db 08h. OOh, Ofh, OOh 

mov ax, ds 



mov es, ax 

mov bx, offset attrdflt 

mov ah, 0f7h 

mov dx, 0018h 

int lOh 



assume attrdflt in 
data segment 
es = data segment 
es:bx = attrdflt 
address 

f7 = define default 
register table 

dx = attribute 
control 1 er 

do it! 



The following example defines a default value for the 
Feature Control register: 



featdflt db OOh 

mov ax, ds 



mov es, ax 

mov bx, offset featdflt 

mov ah, 0f7h 

mov dx, 0028h 

int lOh 



assume featdflt in 

data segment 
es = data segment 
es:bx = featdflt 

address 

f7 = define default 
register table 

dx = feature 
control register 

do it! 
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Function F8 - Read Default Register Table 

Purpose Function F8 reads the table containing default register 
values for any pointer/data chip or single register. 

Input: 

AH = 0F8H 

DX = Port number: 

Pointer/data chips 

Oh: CRT Controller (3?4H) 

8h: Sequencer (3C4H) 

10h: Graphics Controller (3CEH) 

18h: Attribute Controller (3C0H) 

Single registers 

20h: Miscellaneous Output register (3C2H) 
28h: Feature Control register (3?AH) 
30h: Graphics 1 Position register (3CCH) 
38h: Graphics 2 Position register (3CAH) 

? = B for monochrome modes or 0 for color modes 

ES:BX = Points to a table Into which the default values are 
returned. The table must have room for the full set of 
values for the pointer/data chip or single register spec- 
ified. 

Output: 

AX: Restored 
BX: Not restored 
DX: Not restored 
ES: Restored 

Ail other registers restored 
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Function FA - Interrogate Driver 

Purpose Function FA returns a value specifying wlietlier tlie EGA.SYS 
driver is present. 

Input: 

AH = FAh 
BX = 0 

Output: 

AX: Restored 

BX: 0, if EGA.SYS driver is not present 

ES:BX: Pointer to EGA Register Interface version number, if 

present: 
Byte 1: Major release number 
Byte 2: Minor release number (in 1/100ths) 

Example: The following example interrogates tlie driver and displays 



the results: 








gotmsg 


db 


"EGA.SYS driver found". Odh, Oah. 24h 


nopmsg 


db 


"EGA.SYS driver not 


found", Odh, Gah, 24h 


revmsg 


db 


"revision $" 






crlf 


db 


Odh, Oah. 24h 






ten 


db 


10 








mov 


bx, 0 


must be 0 for this call 




mov 


ah. 0fah 


fa 


= interrogate driver 




int 


10h 


interrogate! 




or 


bx, bx 


bx 


= 0 ? 




jnz 


found 


branch if driver present 




mov 


dx, offset nopmsg 


assume nopmsg in data 










segment 




mov 


ah. 09h 


9 = 


= print string 




int 


21h 


output not found message 




jmp 


continue 


that's all for now 


found: 


mov 


dx, offset gotmsg 


assume gotmsg in data 










segment 




mov 


ah. 09h 




9 = print string 




int 


21h 




output found message 




mov 


dx, offset revmsg 


assume revmsg in data 










segment 




mov 


ah, 09h 


9 = 


= print string 




int 


21h 


output "revision " 




mov 


dl. es:[bx] 


dl 


= major release 



number 
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add 


dl. "G" 


mov 


ah, 2 


int 


21h 


mov 


dl, "." 


mov 


ah, 2 


int 


21h 


mov 


al, es:[bx+l] 


xor 


ah, ah 


idiv 


ten 


mov 


bx, ax 


mov 


dl, al 


add 


dl. "0" 


mdv 


ah, 2 


int 


21h 


mov 


dl. bh 


add 


dl. "0" 


mov 


ah. 2 


int 


21h 



mov dx. offset crl 

mov ah, 09h 

int 21h 
continue: 



convert to ASCII 
2 = display character 
output major release 
number 
dl = "." 

2 = display character 
output a period 
al = minor release 
number 
ah = 0 

al = 10ths, ah = 100ths 
save ax in bx 
dl = 10ths 
convert to ASCII 
2 = display character 
output minor release 
IGths 

dl = 100ths 
convert to ASCII 
2 = display character 
output minor release 
100ths 

assume crlf In data 
segment 

9 = print string 
output end of line 
the end 



Using Extended Screen and Keyboard Control 
(ANSI.SYS, ANSICALL.DLL) 

This section explains liow you can issue special control character 
sequences to: 

• Control the position of the cursor 

• Erase text from the screen 

• Set the display mode 

• Redefine the meaning of keyboard keys 

ANSI extended screen and keyboard control sequences are sup- 
ported in the DOS mode by ANSI.SYS, an installable device driver. 

In the OS/2 mode, these control sequences are supported by 
ANSICALL.DLL, a dynamic link module. 

Note: In this section, unless otherwise specified, ANSI refers to both 
ANSI.SYS and ANSICALL.DLL. 

Limitations/Restrictions 

ANSI operates on a per-session basis. 

OS/2 mode ANSI is affected when keys are reassigned in a code page 
environment. ANSI does not provide code page support for key reas- 
signment In the DOS mode. 

Control Sequences 

Control Sequence Syntax 

Each of the cursor control sequences is in the format: 
ESC [ parameters COMMAND 
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ESC 


The 1-byte ASCII code for ESC (1BH). 
It is not the three characters ESC. 


[ 


The character [. 


parame- 
ters 


The numeric values you specify for #. 
The # represents a numeric parameter. 
A numeric parameter is an integer 
value specified with ASCII characters. 
If you do not specify a parameter 
value, or If you specify a value of 0, the 
default value for the parameter Is used. 


COMMAND 


An alphabetic string that represents 
the command. It is case specific. 



For example: 
ESC [2;10H 

could be created using BASIC as follows: 

The IBM Personal Computer Basic 

Version 3.0G Copyright IBM Corp. 1981, 1982, 1983, 1984 
xxxxx Bytes free 

Ok 

open "sample" for output as 1 
Ok 

print #1, CHR$(27);"[2;10H";"x row 2 col 10" 
Ok 

close #1 
Ok 

Notice that "CHR$(27)" is ESC. 
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Cursor Control Sequences 

The following tables contain the cursor control sequences you can 
use to control cursor positioning. 

Cursor Position 



Cursor Position 


Function 


ESC [#;#H 


Moves the cursor to the 
position specified by the 
parameters. The first 
parameter specifies the row 
number and the second 
parameter specifies the 
column number. The 
default value is 1. If no 
parameter is given, the 
cursor Is moved to the 
home position. 



This example copies the file SAMPLE from the previous example, to 
CON, which places the cursor on row 2 column 10 of the screen: 

type sample 
Cursor Up 



Cursor Up 


Function 


ESC [#A 


Moves the cursor up one or 
more rows without 
changing the column posi- 
tion. The value of # deter- 
mines the number of lines 
moved. The default value 
for # is 1 . This sequence is 
Ignored if the cursor is 
already on the top line. 



Cursor Down 
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Cursor Down 


Function 


ESC [#B 


Moves the cursor down one 
or more rows without 
changing the column posi- 
tion. The value of # deter- 
mines the number of lines 
moved. The default value 
for # is 1 . The sequence is 
ignored if the cursor Is 
already on the bottom line. 


Cursor Forward 


Cursor Forward 


Function 


ESC [#C 


Moves the cursor forward 
one or more columns 
without changing the row 
position. The value of # 
determines the number of 
columns moved. The 
default value for # Is 1. 
This sequence is ignored if 
the cursor Is already in the 
rightmost column. 
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Cursor Backward 



Cursor Backward 


Function 


ESC [#D 


Moves the cursor back one 
or more columns without 
changing the row position. 
The value of # determines 

moved. The default value 
for # is 1. This sequence is 
ignored if the cursor is 
already in the leftmost 
column. 


Horizontal and Vertical Position 


Horizontai and Vertical 
Position 


Function 


ESC [#;#f 


Moves the cursor to the 
position specified by the 
parameters. The first 
parameter specifies the line 
number and the second 
parameter specifies the 
column number. The 
default value is 1. If no 
parameter is given, the 
cursor is moved to the 
home position- 



Cursor Position Report 


Cursor Position Report 


Function 


ESC [#;#R 


The cursor sequence report 
reports the current cursor 
Dosition throuoh the 
standard Input device. The 
first parameter specifies the 
current line and the second 
parameter specifies the 
current column. 


Device Status Report 


Device Status Report 


Function 


ESC [6n 


The console driver gives a 
cursor position report 
sequence on receipt of 
device status report. 



Note: Do not use the Device Status Report as part of a prompt. 

This example tells ANSI to put the current cursor position (row and 
column) in STDIN. Then the program reads it from STDIN and outputs 
to STDOUT. 
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PROGRAM dsr(INPUT,OUTPUT); 



VAR 

f:FILE OF CHAR; 
key: CHAR; 



FUNCTION inkey:CHAR; 


{ read character } 


VAR 


{ from the } 


chrCHAR; 


{ keyboard buffer } 


BEGIN 




READ(f.ch); 




inkey:»ch 




END; 




BEGIN 




ASSIGN(f.'user'); 




RESET (f); 




WRITE(CHR(27),'[6n'); { issue a DSR } 


key:=inkey; 


{ read up to } 


key:=inkey; 


{ first digit } 


key:=inkey; 


{ of the row } 


WRITE('row ' .inkey.inkey, ' column '); 


key:=inkey; 


{ skip to column} 


WRITE(inkey,1nkey) 


{ write column } 


END. 




Save Cursor Position 




Save Cursor Position 


Function 


ESC [s 


The current cursor position 
is saved. This cursor posi- 
tion can be restored with 
the restore cursor position 
sequence (see below). 



Restore Cursor Position 



Restore Cursor Position 


Function 


ESC [u 


Restores the cursor to the 
value it had when the 
console driver received the 
save cursor position 
sequence. 



Erasing 

The following tables contain the control sequences you can use to 
erase text from the screen. 



Erase in Display 



Erase in DIspiay 


Function 


ESC [2J 


Erases all of the screen and 
the cursor goes to the home 
position. 


Erase in Line 


Erase in Line 


Function 


ESC [K 


Erases from the cursor to 
the end of the line and 
includes the cursor posi- 
tion. 



Controlling Display Mode 

The following tables contain the control sequences you can use to set 
the mo^e of operation. They are: 

• Set Graphics Rendition (SGR) 

• Set Mode (SM) 

• Reset Mode (RM) 
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Set Graphics Rendition (SGR) 



SGR 



Function 



ESC [#;... ;#m Sets the character attribute 

specified by the parameters. All 
following characters have the 
attribute according to the 
paranneters until the next occur- 
rence of SGR. 



'ameter 


Meaning 


0 


All attributes off 




(normal white on 




black) 


1 


Bold on (high inten- 




sity) 


4 


Underscore on 




(mono-compatible 




modes) 


5 


Blink on 


7 


Reverse video on 


8 


Canceled on (invis- 




ible) 


30 


Black foreground 


31 


Red foreground 


32 


Green foreground 


33 


Yellow foreground 


34 


Blue foreground 


35 


Magenta foreground 


36 


Cyan foreground 


37 


White foreground 


38 


Reserved 


39 


Reserved 


40 


Black background 


41 


Red background 


42 


Green background 


43 


Yellow background 


44 


Blue background 


45 


Magenta background 


46 


Cyan background 


47 


White background 



Set Mode (SM) 



SM 


Function 


ESC [ = #h 


Invokes the screen width or 


or ESC[ = h 


type specified by the 


or ESC [ = 0h 


parameter. 


or ESC[?7h 


Parameter 


Meaning 




0 


40x25 black and 






white 




1 


40x25 color 




2 


80x25 black and 






white 




3 


80x25 color 




4 


320x200 color 




5 


320x200 black 






and white 




6 


640x200 black 






and white 




7 


Wrap at end of 






line. (Typing 






past end-of-line 






results in new 






line.) 


Reset Mode (RM) 


RM 


Function 


ESC [ = #l 


Parameters are the same 


or ESC [ = 1 


as Set Mode (SM) except 


or ESC [ = 01 


that parameter 7 resets 


or ESC [?7I 


wrap at end-oMine mode 




(characters past end-of-line 




are thrown away). 
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Keyboard Key Reassignment 

When the application does a KbdStringIn call, the reassigned l<ey's 
ASCII code is converted to the specified string and is passed bacl< to 
the calling application. 

OS/2 mode ANSI is affected when keys are reassigned in a code page 
environment. ANSI "remembers" the code page under which a key is 
reassigned. The keyboard subsystem checks for reassigned keys 
when the application calls the KbdStringIn function. When a reas- 
signed key is detected, the ANSI support: 

• Checks to see what code page the requestor is running under. 

• Looks internally to see if the key has been reassigned under that 
code page. 

• if there is a key reassignment for that code page, gives the reas- 
signment string. 

• Otherwise, gives the original ASCII codes. 

A maximum storage of 64Kb may be allocated to OS/2 mode ANSI 
reassigned key definitions. 

The following table contains the control sequences you can use to 
redefine the meaning of keyboard keys. 
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The control sequence Is: 


Function 


ESC [#;#;...#p 
or ESC ["string"p 
or ESC [#;"string";#; 

#;"string";#p 
or any other combination of 

strings and decimal 

numbers 


The first ASCII code in the 
control sequence defines 
which code is being 
mapped. The remaining 
numbers define the 
sequence of ASCII codes 
generated when this l<ey is 
intercepted. However, if the 
first code in the sequence is 
0 (NULL) the first and 
second code mal<e up an 
extended ASCII redefinition 



Here are some examples: 

To execute these examples, you can either: 

• Create a file that contains the following statements and then use 
the TYPE command to display the file that contains the statement. 

• Execute the command at the OS/2 prompt. 
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1. Reassign the Q and q key to the A and a (and the other way as 
well): 

Creating a File: 

ESC [65:81p A becomes Q 

ESC [97;113p a becomes q 

ESC [81;65p Q becomes A 

ESC [113;97p q becomes a 

At the OS/2 Prompt: 

prompt $e[65:81p A becomes Q 

prompt $e[97;113p a becomes q 

prompt $e[81;65p Q becomes A 

prompt $e[113;97p q becomes a 

2. Reassign the F10 key to a DIR command followed by a carriage 
return: 

Creating a File: 
ESC [0;68;"dir";13p 
At the OS/2 Prompt: 
prompt $e[0;68;"dir";13p 

The $e is the prompt command characters for ESC. The 0;68 is 
the extended ASCII code for the F10 key; 13 decimal is a carriage 
return. 

3. The following example sets the prompt to display the current 
directory on the top of the screen and the current drive on the 
current line. 

prompt $e[s$e[l:30f$e[K$p$e[u$n$g 

If the current directory is C:\FiLES, and the current drive is C, this 
example would display: 

C:\FILES 

C> 
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4. The following DOS mode assembly language program reassigns 
the F10 key to a DIR B: command followed by a carriage return. 



TITLE SETANSI.ASM - SET F10 TO STRING FOR ANSI. SYS 
CSEG SEGMENT PARA PUBLIC 'CODE' 

ASSUME CS : CSEG. DS: CSEG 

ORG IGOH 
ENTPT: JMP SHORT START 

STRING DB 27,'[0;68;"DIR B:";13P' ;Redefine F10 key 
STRSIZ EQU $-STRING ; Length of above message 

HANDLE EQU 1 ; Pre-defined file 

; Handle for standard output 



START 



PROC 


NEAR 




MOV 


EX. HANDLE 


; Standard output device 


MOV 


CX, STRSIZ 


;Get size of text to be sent 


MOV 


DX, OFFSET STRING 


;Pass offset of string 






;To be sent 


MOV 


AH.40H 


;Function="write to device" 


INT 


21H 


;Call DOS 


RET 




; Return to DOS 


ENDP 







CSEG ENDS 

END ENTPT 
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Diskette Device Driver 

The floppy disk device driver is able to run in a multitasking, dual- 
mode environment. 

The following functions are provided. 

• Read 

• Write 

Reading and writing can be done in either of two modes. Abso- 
lute mode allows the user to specify a logical sector to be used 
for the starting I/O location. The other mode requires the track 
and sector number to be specified. 



• Verify 

• Format 

With this function the user is able to determine if the drive is 
present, if the direct access storage device (DASD) is a diskette 
with change line available/not available, or if the DASD is a fixed 
disk. 



• Get/Set Device Parameters 
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Fixed Disk Device Driver 



The fixed disk device driver Is able to run In a muititasklng, dual 
mode environment. 

The following functions are provided. 

• Read 

• Write 

Read and write requests can be made in either of two modes. 
Absolute mode allows the user to specify a logical sector to be 
used for the starting I/O location. The other mode requires the 
cylinder and head and sector number to be specified. 

• Verify 

• Format 

• Get/Set Drive Parameters 

With this function the user Is able to determine the number of 
consecutive drives that are attached, the maximum usable value 
for head number, the maximum usable value for cylinder number, 
and the maximum usable value for sector number. 

The user Is able to determine if a DASD Is present. If the DASD Is 
a diskette with change line available/not available, or if the DASD 
is a fixed disk. If the DASD is a fixed disk, the number of 512-byte 
blocks contained Is returned. In addition, the disk device driver 
has some special support code for DOS mode applications which 
can issue INT 13H, which also runs in user state. 

Greater than Z2Mb Partitioned support 

Large fixed disk (greater than 32Mb) are supported by OS/2 with par- 
titioning of the disk. The extended partition Is indicated by a system 
ID byte of 05H in the partition table of the Master Boot (Start-up) 
Record. This partition cannot be started, and programs that can set 
startable partitions (such as OS/2 FDiSK) will not allow the partition 
to be marked as able to start. 

Note: This extended partition support can be used on any fixed disk 
supported by OS/2. 
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The extended DOS partition can be created only if a primary DOS par- 
tition already exists on a startable drive. A Primary DOS partition is a 
partition with a system ID byte of 01 H or 04H. If the drive cannot be 
started, then an extended DOS partition may be created without 
having a primary DOS partition. 

The Extended DOS Partition starts and ends on a cylinder boundary. 
Extended DOS Partition Architecture 

The Extended DOS Partition consists of a collection of extended 
volumes which are linked together by a pointer in the extended 
volumes' extended start-up record. An extended volume consists of 
an extended start-up record and one logical block device. An 
extended volume created within the extended DOS partition can be 
any size from one cylinder long up through the maximum available 
contiguous space in the extended DOS partition. However, in OS/2 an 
extended volume cannot be larger than 32Mb due to the limitations of 
the FAT file system. All extended volumes must start and end on a 
cylinder boundary. An extended volume will correspond to an image 
of a physical disk. The extended start-up record corresponds to the 
master start-up record at the beginning of an actual physical disk and 
the logical block device corresponds to the DOS partition that is 
pointed to by the master start-up record. 

Therefore, the logical block device begins with a normal DOS start-up 
sector if it is a DOS logical block device (system id= 1 or 4). This 
logical block device must start on a cylinder and head boundary and 
follows the extended start-up record on the physical disk. The logical 
block device and the extended volume both end on the same cylinder 
boundary. 

Each extended volume contains an extended start-up record, located 
in the first sector of the disk location assigned to it. This extended 
start-up record contains the 55AAH signature ID byte. This allows 
programs that look at the extended (master) start-up record to be 
compatible. This extended start-up record also contains a partition 
table, which can contain only 2 types of entries. The start-up code is 
not critical, as the devices are not considered startable. The start-up 
code may simply report a message indicating an unstartable partition 
if it is executed. 
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The partition table portion of tlie extended start-up record is tiie same 
as tlie partition table structure in the master start-up record. This 
structure has four partition entries of 16 bytes each. The system ID 
byte must be filled in for ail four entries with one of the following 
values: 

OOH No space allocated in this entry. 

01 H DOS partition up to 16Mb 

04H DOS partition with 32Mb > SIZE > 16Mb 

05H Maps out area assigned to the next extended volume. Serves 
as a pointer to the next extended start-up record. 

06H Reserved. 

if the system ID byte is 0 then the values in that partition table entry 
will be set to 0. 

If OS/2 detects any values other than 01 H or 04H, It will ignore that 
entry and not attempt to install the logical blocl< device. This will 
allow future expansion of devices in this area without problems of 
compatibility with earlier systems. 

The partition start and end fields (C,H,S) will be filled in for any of the 
four partition entries in an extended start-up record that have one of 
the above system ID bytes. This will allow a program such as FDISK 
to determine the allocated space in the extended DOS partition, as 
well as allowing the device drivers to determine the physical DASD 
area that belongs to it. The partition start and end fields (C,H,S) for 
the partition entry that points to the logical block device (system ID 
01 H, 04H, or 06H) map out the physical boundaries of the logical block 
device. They are offset relative to the beginning of the extended 
start-up record that the entry resides In. The partition start and end 
fields (C,H,S) for the partition entry that points to the next extended 
volume (system ID 05H) map out the physical boundaries of the next 
extended volume. They are relative to the beginning of the entire 
physical disk. 

The relative sector and number of sector fields will be set up differ- 
ently depending on what system ID byte is used. If 01 H, 04H or 06H is 
in the system ID field for that extended partition entry (pointer to the 
logical block device), the relative sector field will be set up as an 
offset from (and including) the start of the extended start-up record for 
the associated extended volume. The number of sectors (size) field 
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will be filled in with the size of the created logical block device area, 
In other words, the number of sectors mapped out by the start and 
stop cylinder/track/sector fields. The size of the extended volume 
can be calculated by adding the relative sector field and the sector 
size field of the associated extended start-up record. 

If the system ID byte is 05H, then the relative sector field is the offset 
(of the next extended volume) in sectors from the start of the entire 
extended DOS partition. The number of sectors field is not used in 
this field, and will be filled with OOH's. 

This architecture allows only one logical block device to be defined 
for each extended start-up record. Therefore, only a maximum of two 
partition entries at a time is used in each extended start-up record; an 
entry with system ID byte of (01 H, 04H, or 06H) and an entry with ID of 
05H, which is the pointer to the next extended volume. Although only 
two entries can be used, a program installing these devices will not 
assume that the first two entries will be the non-zero entries. 

Installing Block Devices In the Extended Partition 

To install block devices, the device drivers will first install the 
primary DOS partitions on both the 80H and 81 H physical drives if any 
exist. This will insure that an existing drive letter (D:) on the 81 H 
drive will remain the same. After these devices are installed, on the 
80H drive, the drivers will look for the existence of the extended DOS 
partition. If one exists, then it will look at the first sector of the 
extended DOS partition for the first extended start-up record, if there 
is a valid system ID (01 h, 04h, or 06h) in any of the four partition 
entries, the device is installed and assigned the next available drive 
letter. This will occur before any CONFIG.SYS device drivers are 
loaded so the FDISK will correctly display the drive letter when space 
is allocated for the drive. 



9-141 



The first extended start-up record (in tiie extended DOS partition) is a 
special case because It Is possible there will not be a device to be 
Installed defined in the partition table. The first device might have 
been created and then deleted at some time, but the first extended 
start-up record is needed to point to the next one, if one exists. Any 
other extended start-up record will always have a device to be 
installed. 

An extended start-up record may not contain a device that will be 
installed by that driver. For example, a logical block device with a 
system ID byte of 06H would not be installed In OS/2. 

Once a device has been Installed (or the special cases above occurs), 
the device driver will search the other partition entries for a system 
ID byte of 05H, indicating that another device (extended volume) 
exists. If a 05H is not found, there are no more logical block devices 
(extended volumes) in the extended DOS partition. 

If a 05H system ID is found, the start location In that partition entry 
will be read in order to find the location of the next extended start-up 
record (extended volume). When located, it will be read in and then 
the process repeated in order to install additional devices. 

Once all the valid devices for a physical drive have been installed, 
the next physical drive will be examined and the entire process 
repeated. 

A device driver will not assume any order dependency when 
searching for a particular system ID byte in an extended start-up 
record. Ail four possible entries in a extended start-up record parti- 
tion table will be searched before a driver decides that a particular 
system ID byte does not exist. 
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Creating Block Devices In the Extended DOS Partition 

To create the structure for an extended volume in the extended DOS 
partition, FDISK will determine if there is available space in the 
extended DOS partition and If less than 24 total devices are allocated 
in the system. The maximum number of block devices allowed is 26, 
and two are used by diskettes A: and B:. If so, then the program wilt 
create an extended start-up record at the space located, with a parti- 
tion entry filled in with the size and location information for that 
logical block device. If this Is not the first extended start-up record, 
the program will back up to the last extended start-up record In the 
chain (as linked by the 05H entries), and create a partition entry in 
that extended start-up record that has the size and location data for 
the newly created record. This action will create the pointer required 
to locate the newly created start-up record. 

If this is the first extended start-up record (in the extended DOS parti- 
tion), only the size, type and location of the logical block device need 
to be put into a partition entry. The start of the extended DOS parti- 
tion in the master start-up record will serve as a pointer to this 
extended volume. 

Deleting Block Devices In the Extended DOS Partition 

To delete a block device, the program will set to 0 the 16-byte parti- 
tion entry that contained the system ID byte that indicated the device 
type (01 H, 04H, or 06H). Also, if In the same extended start-up record 
there exists a partition entry with system ID of 05H, indicating that 
another extended volume exists, this information will be copied to the 
05H partition entry of the previous extended start-up record. There is 
one exception to this rule: if the logical block device deleted is at the 
beginning of the extended DOS partition, only the partition entry indi- 
cating the device type would be set to 0. The 05h pointer information 
will be left In place. 



9-143 



Layout 



of Block Devices In the Extended DOS Partition 



Master Boot Record (Note 1) 
(Note 2) 



> 4 2 5 0 55AA 



Primary DOS Partition (Note 4) 
DOS C: drive 32Mb > size 



Other Operating system Partition (XENIX) (Note 5) 



Extended Boot Record (Note 6) 
( Note 7) > 



4 5 0 0 55AA 



LOGICAL b\ock device D: (Note 8) 
32Mb > Size > 16Mb 



Extended Boot Record (Note 9) 

(Note 10) > 1 5 0 0 55AA 



LOGICAL block device E: 
Size < 16Mb 



Extended Boot Record 
(Note 11) > 



6 5 0 0 55AA 



Area reserved for OS/2 use (Note 12) 



Extended Boot Record 
(Note 13) > 



4 0 0 0 55AA 



LOGICAL blocl< device G: 
32Mb > Size > 16Mb 



Free Space in Extended Partition 



Free Space not allocated to any partition 



Note 1 Master start-up (boot) record code, starting at Trk 000, Hd 
00, Sec 01 of disk 80H or 81 H. 
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Note 2 Partition table for master start-up record. See "Partition 

Table for Master Start-up Record" on page 9-146 for layout. 
The 4 is tlie system ID byte in tlie partition table that indi- 
cates a DOS partition bigger than 16Mb, the 2 is a XENIX 
partition, and the 05H maps the extended DOS partition. 

Note 3 55AAH is the signature to validate the master start-up 
record. 

Note 4 Primary DOS area, must reside entirely in first 32Mb of disk. 
C: is block device 801-1. D: is block device 811-f if it exists. 
This partition has a maximum size of 32Mb. 

Note 5 Other operating system on disk; XENIX in this example. 

Note 6 Extended start-up record for extended volume that corre- 
sponds to logical block device D:. (This assumes only BOH 
block device exists.) If 81 H block device exists, then this 
would be block device E:. 

Note 7 Logical block device D: partition table entry. This has a 

maximum size of 32Mb, which is indicated by the system ID 
of 4. This must set the logical DOS block device as starting 
at the next cylinder and head boundary. The 05h system ID 
byte in the second partition entry maps out the space allo- 
cated to the next extended volume. The starting 
cyl/sec/head in the partition entry with ID of 05H is the 
location of the next extended start-up record of the next 
extended volume. 

Note 8 Logical block device D:. Logical DOS devices always begin 
with a DOS start-up record as does the primary DOS parti- 
tion. 

Note 9 Extended start-up record for logical block device E:. 

Note 10 Partition table entry for logical block device E:. This logical 
DOS block device is less than 16Mb, as indicated by the 
system ID of 01 h. The entry with system ID of 05H maps out 
the space allocated to the next extended volume. 

The system ID byte of 06IH indicates a reserved area. These 
areas are not limited to 32Mb and may not be used in OS/2. 
This would have a block device letter of F: in a system that 
would recognize system ID 06h. Note also that a pointer 
exists to the next extended volume. 

Reserved 



Note 11 



Note 12 



9-145 



Note 13 Partition table entry for final DOS logical block device. Note 
the absence of 05h ID byte means that there are no other 
extended volumes allocated in the extended DOS partition. 
This would have a block device letter of G: if the previous 
logical block device was recognized. Otherwise it would be 
R. 

Partition Table for Maeter Start-up Record 



Offs Purpose 




Head 


Sector 


Cylinder 


1BE Partition 1 begin 


boot ind 


H 


S 


CYL 


1 Partition 1 onri 


syst ind 


H 


S 


CYL 


1C6 Partition 1 rel sect 


Low word 


High word 


1CA Partition 1 M sects 


Low word 


FHigh word 


portitinn 0 hp^nin 


boot ind 


H 


S 


CYL 


KarTiTion £. ena 


syst ind 


H 


s 


CYL 


inR pArtitinn P rpl Qppt 


Low word 


High word 


1 DA Partition 2 ^ sects 


Low word 


High word 


1DE Partition 3 begin 


boot ind 


H 


8 


CYL 


1 E2 Partition 3 end 


syst ind 


H 


S 


CYL 


1E6 Partition 3 rei sect 


Low word 


High word 


1EA Partition 3 # sects 


Low word 


High word 


1EE Partition 4 begin 


boot ind 


H 


S 


CYL 


1P2 Partition 4 end 


syst Ind 


H 


S 


CYL 


1F6 Partition 4 rel sect 


Low word 


High word 


1FA Partition 4 # sects 


Low word 


High word 


1FE Signature 
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BPB and Get Device Parameters for Extended Volumes 

For purposes of the BIOS Parameter Block (BPB) and Get Device 
Parameters (Generic lOCtI), an extended volume appears to the 
system as a virtual physical fixed disk. The extended start-up record 
will correspond to the master start-up record of a real fixed disk and 
the logical block device will correspond to the primary DOS partition. 

This means that the BPB of the logical DOS block device of the 
extended volume will describe the environment In the extended 
volume; this consists of the extended start-up record and the logical 
block device. The meaning of the fields will be consistent to the 
meaning of the fields for the primary DOS partition; they relate to the 
entire physical disk, the primary DOS partition, and the master 
start-up record. For example, the number of hidden sectors will be 
the distance from the beginning of the extended start-up record (of 
the extended volume in question) to the start of the logical DOS block 
device (the DOS start-up record). The number of sectors field will 
describe only the logical block device just as It normally only 
describes the primary DOS partition. 

Category 8 Generic iOCti Commands 

The philosophy described above also applies to the disk generic lOCtI 
commands. For any logical block device of an associated extended 
volume; physical cylinder, head, sector I/O is mapped to within the 
extended volume. Cylinder 0, head 0, sector 1 is mapped to the 
extended start-up record. An error condition will be generated for 
any attempt to do C,H,S i/0 beyond the size of the extended volume 
in question. 

Category 9 Generic iOCtI Commands 

Category 9 generic lOCtI commands are used to access the entire 
physical fixed disk without consideration of logical volumes. Physical 
cylinder, head, sector begin at the start of the physical drive instead 
of at the beginning of an extended volume. "Get physical device 
parameters" describes the entire physical device. 
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EXTDSKDD.SYS Device 



This installable device driver allows you to access and use a disk 
device by referencing a logical drive letter. The format of the 
CONFIG.SYS DEVICE statennent is: 

DEVICE=EXTDSKDD.SYS /D:ddd[T:ttt] [/S:ss] 
[/H:hh] [/C] [/N] [/F:f] 

These parameters are defined as follows: 

/D:ddd specifies the physical drive number. A physical drive has the 
value 0 through 255. A value of 0 specifies the first physical diskette 
drive and is referenced as drive A from the OS/2 command line. 

The value 1 specifies the second physical diskette drive. 

The value 2 specifies the third physical diskette drive (which must be 
external). 

A fixed disk drive can be partitioned into many different logical drives 
using the FDISK utility. Assigning a new drive letter to the physical 
fixed disk in this environment is not meaningful and Is not supported. 

/T:ttt specifies the number of tracks per side (1-999). The default is 80 
tracks per side. 

/S:ss specifies the number of sectors per track (1-99). The default is 
nine sectors per track. 

/H:hh is the maximum number of heads (1-99). The default number is 
two heads. 

/C specifies that Changeline support is required. This is meaningful 
only on machines that support diskette Changeline, such as the IBM 
Personal Computer AT and PS/2. 
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/F:f specifies the device type (form factor). Clioose from the list 
below. The default is 2. 

Value Device 

0 160/180 KB 

0 320/360 KB 

1 1.2 MB 

2 720 KB 
7 1.44 MB 

The general rules for drive letter assignment are discussed following 
these few simple examples. In the first three examples It is assumed 
that there are no extended DOS partitions on the IBM Personal Com- 
puter AT fixed disk. 

Example 1 - To set up a logical drive (D) for a 720 KB external 
diskette drive on a IBM Personal Computer AT (one internal diskette 
drive and one fixed disk), use the following command: 

DEVICE=EXTDSKDD.SYS /D:2 

Example 2 - To be able to copy from a 720 KB external diskette drive 
to the same drive, put the same command in the CONFIG.SYS file 
twice, which (for an IBM Personal Computer AT) assigns the logical 
drive letters D and E to the drive. 

DEVICE=EXTDSKDD.SYS /D:2 
DEVICE=EXTDSKDD.SYS /D:2 

Example 3 - You can use EXTDSKDD.SYS to copy from an internal 
drive to the same Internal drive. Assume you have an IBM Personal 
Computer AT with a 1.2Mb drive as the first diskette drive and a 
320/360 KB drive as the second physical diskette drive and a fixed 
disk. The CONFIG.SYS command would be: 

DEVICE=EXTDSKDD.SYS /D:0 /T:80 /S:15 /H:2 /C /F:l 

This assigns the logical drive letter D to the first diskette drive. It can 
now be referenced as A and D. The command 

A>copy filel d: 

copies "filel" from one diskette to another diskette using the 1.2Mb 
drive only. OS/2 prompts you to insert the diskette for the appro- 
priate logical drive. 
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Example 4 - If in the previous example FDISK had been used to set up 
an extended DOS partition on the Personal Computer AT fixed disk, 
the same DEVICE = statement in CONFIG.SYS would result in the 
logical drive letter E (instead of D) being assigned to the first disl<ette 
drive. It can now be referenced as A and E. The command 

A>copy filel e: 

copies "filel" from one diskette to another diskette using the 1.2Mb 
drive only. OS/2 prompts you to insert the diskette for the appro- 
priate logical drive. 

General Rules For Drive Letters: The first physical internal diskette 
drive is assigned A. The second internal diskette drive is assigned B. 
The letters beginning with C are assigned in the order devices (or 
device drivers) are encountered. The existence of internal physical 
devices (diskettes and fixed disks) is checked first including partitions 
on the fixed disks; then the CONFIG.SYS file is checked for device 
drivers. For OS/2 to recognize an external physical device the 
CONFIG.SYS file must have the correct device driver information. 

The drive letter B automatically is used, even if there is only one 
physical diskette drive, that is, on machines with only one diskette 
drive, there are two logical diskette drives A and B. In this case, the 
parameter /D:1 is an error. The first fixed disk, or the first block 
device driver, cannot have a drive letter assigned lower than C. On 
each fixed disk a drive letter is assigned for each primary and 
extended DOS partition. 

For machines with an external drive, if the external device driver is 
loaded twice, where /D:dd is the same, it generates two logical drives 
for the one physical drive. This provides the ability to transfer data 
from one diskette to another in that same drive. 

The same concept can also be applied to internal drives. In this case, 
OS/2 automatically loads a disk device driver for the drive at setup 
time. By including a DEVICE = EXTDSKDD.SYS in the CONFIG.SYS 
file for the same drive, two drive letters will be associated with the 
same drive. The command 

DEVICE=EXTDSKDD.SYS /D:Q 

in the CONFIG.SYS file at start-up time causes OS/2 to load another 
diskette driver for the first diskette drive. As described above, the 
drive letter depends on the number of diskette drives and the number 
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of fixed disks In the machine. For a machine with two diskette drives 
and a fixed disk that does not have any extended DOS partitions, the 
logical drive letter for the first diskette is drive D. With this setup you 
can copy files from the first physical diskette drive to the first logical 
diskette drive by referencing them as A and D. 

The following table describes the logical drive letter assigned to the 
external device driver for certain machine configurations and values 
of /D. 

Note: More than one external device driver can be installed at the 
same time even though this table shows one external device driver. 
The existence of any VDISKs will not affect the drive letter assign- 
ments described below if the DEVICE =VDISK.SYS commands are 
a^ter the DEVICE = EXTDSKDD.SYS commands in the CONFIG.SYS 
file. 



Internal 
diskette 
drives 


Internal 
fixed 
disk 
drives * 


External 

drives 

attached? 


pnysicai 
drive 
number 
(/D:ddd) 


Logical 
drive 
ietter 
assigned 




0 


No 


0 


C: 




0 


No 


1 


error 




1 


No 


0 


D: 




1 


No 


1 


error 




1 


No 


128 


error 




2 


No 


0 


E: 




2 


No 


1 


error 




2 


No 


128 


error 




0 


Yes 


0 


C: ** 




0 


Yes 


1 


error 




0 


Yes 


2 


C: 
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internal 
uiSKene 
drives 


internal 
iixea 
disic 
drives * 


External 

arives 

attaclied? 


Physical 
drive 
number 
(/D:ddd) 


Logical 
drive 
letter 
assigned 




1 


Yes 


0 


D: 




1 


Yes 


1 


error 




1 


Yes 


2 


D: 




1 


Yes 


128 


error 




2 


Yes 


0 


E: 




2 


Yes 


1 


error 




2 


Yes 


2 


E: 




2 


Yes 


128 


error 




2 


Yes 


129 


error 


2 


0 


No 


0 


C: 


2 


0 


No 


1 


C: 


2 


0 


No 


2 


error 


2 


1 


No 


0 


D: 


2 


1 


No 


1 


D: 


2 


1 


No 


2 


error 


2 


1 


No 


128 


error 


2 


2 


No 


0 


E: 


2 


2 


No 


1 


E: 


2 


2 


No 


2 


error 


2 


2 


No 


128 


error 


2 


2 


No 


129 


error 


2 


0 


No 


0 


C: ** 
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Internal 
drives 


Internal 

fIVAfI 

disk 
drives * 


External 
attached? 


Physical 
Olive 
numlMr 
(/D:ddd) 


Logical 

letter 
assigned 


2 


0 


Yes 


1 


C: ** 


2 


0 


Yes 


2 


C: 


2 


1 


Yes 


0 


D: ** 


2 


1 


Yes 


1 


D: ** 


2 


1 


Yes 


2 


D: 


2 


1 


Yes 


128 


error 


2 


2 


Yes 


0 


E: ** 


2 


2 


Yes 


1 


** 


2 


2 


Yes 


2 


E: 


2 


2 


Yes 


128 


error 


2 


2 


Yes 


129 


error 



* These values assume that there are no extended DOS partitions 
on the fixed dislc(s). 

** The external drive is not recognized. 

Note that a physical drive number above 127 is an error. 
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Printer Device Driver 



The printer device driver runs in a multitasl<ing, dual-mode environ- 
ment. 

The following functions are supported: 

• Initialize Printer Device Driver 

• Print Character 

• Return Printer Device Driver Status 

• Open Device 

• Close Device 

• Deinstall 

• Generic lOCtI functions 

- Set/Return Frame Control 

- Set/Return Infinite Retry 

- Initialize Printer Port 

- Return Printer Port Status 

- Register/Query Monitor Support 

- Activate Code Page/Font 

- Query Code Page/Font 

- Verify Code Page/Font 

When the user asks for printer status with the generic lOCtI request, 
the following Information Is returned: 

• Busy/not busy 

• Acknowledge 

• Out of paper 

• Selected 

• I/O error 

• Timeout 

The printer device driver provides character device monitor support 
on a per device basis. The printer device driver supports the regis- 
tration of two monitor chains. The first chain (INDEX= 1) is normally 
considered to be the data chain and Is used by the printer device 
driver to send character data to a monitor. The second chain 
(INDEX =2) is normally considered to be the code page chain, but it is 
used by the printer device driver only to receive the results of a code 
page request. The code page request sent to the monitor was per- 
formed using the first chain (INDEX=1). 
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The printer spooler is an example of a monitor that registers itself on 
both the data chain and the code page result chain. The input buffer 
specified when the spooler registers INDEX = 2 is never used by the 
spooler. All data and code page requests from the printer device 
driver to the spooler on one chain are sent to Insure that the spooler 
processed the requests in order. The second chain was implemented 
to enhance processing. Processes that issue code page requests are 
blocked until they receive an Indication that their request is valid. 
The second chain allows a monitor to respond to the printer device 
driver quickly and efficiently. 

Therefore, printer device driver monitors must be designed with 
extreme care and thought must be given to their position in the chain 
when other monitors are Involved. The following items list some of 
the possibilities: 

Notes: 

1. If a monitor wishes only to process character data and it is the 
only monitor in the chain, or it is registered to be in a position to 
process the data after the spooler, it only needs to register on the 
data chain (INDEX= 1). This monitor would never see the code 
page requests from the spooler, because the spooler sends these 
requests out on the code page result chain. If the spooler wasn't 
part of the chain, then the printer device driver would never issue 
the code page requests. 

2. If a monitor wishes to process both the character data and the 
code page requests and it is the only monitor in the chain, it must 
register itself on both the data and code page result chains. It 
must also expect to receive both the data and code page requests 
on the data chain, it must respond to the code page requests on 
the result chain as quickly as possible. 

3. If a monitor wishes to process both the character data and the 
code page requests and its position in the chain is after the 
printer spooler, it must expect to receive the character data from 
the spooler on Its data chain (INDEX= 1) and the code page 
requests from the spooler on the code page chain (INDEX = 2). A 
monitor in this situation would not be able to easily synchronize 
the code page requests with the data requests; the spooler wilt 
pass the code page results along the result chain before all the 
data has been spooled and released. 
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4. If a monitor wishes to process botli the character data and the 
code page requests and its position in the chain is before the 
printer spooler, it registers itself on the data chain (INDEX = 1). 
The spooler will register itself on both chains. All data and code 
page requests will be sent to the first monitor on the data chain. 
This monitor must pass on to the spooler ail the information it 
receives, in the order received. 

The printer device driver passes the character Information to the 
monitors in data packets. The character information in the data 
pacl<ets is preceded by control information. The maximum size of the 
data packet which consists of both the control Information and the 
character data is 134 bytes. This value Is used to calculate the size of 
the monitor input/output buffers required for the DosMonReg call. 



Control 



Data 



Byte 0 
Monitor Flags 



Byte 1 
Device Dep Flags 



Word 2 



System File Number 



Word 4 



Character Data 



The printer device driver passes the code page Information to the 
monitors in data packets. The code page information In the data 
packets Is preceded by control information. 
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Control 



Code Page 
Information 



Byte 0 
Monitor Flags 



Byte 1 
Device Dep Flags 



Word 2 



System File Number 



Byte 4 



Byte 5 



Command Byte 



Reserved 



Word 6 



Reserved 0 



Word 8 



Return Code Area 



Word A 



Code Page Value 

Word C 
Font Value 



The printer device driver is in INIT MODE wlien its strategy routine is 
called with a request packet containing the INIT command. The 
initialization code runs in the OS/2 mode at the application privilege 
level with I/O privilege. 

The printer device driver will handle print requests received at its 
strategy entry point from the file system in the form of request 
packets as well as INT17H software interrupt requests received from 
the DOS mode while in user mode. 

The printer device driver has three printer specific lOCtI commands 
to support the code page and font switching provided in OS/2. All of 
the actual code page and font switching function for printers Is pro- 
vided by the code page switcher spooler. When the spooler is 
started, it checks to see if code page support is required. If it is, the 
spooler will cause the code page switcher support to be loaded and 
initialized. In order to support these lOCtIs, there are Font Monitor 
Buffer Command/responses in the monitor interface to the spooler. 
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The functions provided by the lOCtIs and Font Monitor Buffer 
Command/responses are: 

• Activate Font 

• Query Active Font 

• Verify Font 

These lOCtis and monitor code page and font buffer 
command/responses are described in detail in "Printer Device Driver 
Interfaces" on page 9-159. 

Activate Font: Refer to "Printer/Spooler Structure" on page 6-55, 
when an application within a process issues a DosOpen for a printer 
(i.e. LPT1, LPT2, LPT3 or PRN). The file system Issues an Activate 
Font lOCtI to the printer device driver to set the active code page and 
font according the active code page of the process malting the open 
request. 

An application within a process may also issue the Activate Font 
lOCtI to the printer device driver by using the handle returned from 
the DosOpen at any time. This allows the application to change the 
active code page and font in the middle of its print job. 

When the printer device driver receives the Activate Font lOCti, if the 
spooler or another monitor is registered, the printer device driver will 
use the Font Monitor Buffer command to send the Activate Font 
command to the registered monitor in its monitor input buffer. If the 
spooler, or another monitor, is not registered, the printer device 
driver will return the appropriate return code to the caller of the Acti- 
vate Font lOCtl. 

Query Active Font: When the printer device driver receives the Query 

Active Font lOCtI, if the spooler or another monitor is registered, the 
printer device driver will use the Font Monitor Buffer command to 
send the Query Active Font command to the registered monitor in its 
monitor input buffer. The monitor will return the active code page 
and font information to the printer device driver in its monitor output 
buffer. The printer device driver then returns the active code page 
and font information to the caller of the Query Active Font lOCtl. 

If the spooler, or another monitor, is not registered, the printer device 
driver will return the appropriate return code to the caller of the 
Query Active Font lOCtl. 
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Verify Font: When the printer device driver receives the Verify Font 
lOCtI, if the spooler or another monitor Is registered, the printer 
device driver will use the Font Monitor Buffer command to send the 
Verify Font command to the registered monitor in its monitor input 
buffer. The monitor will return whether the specified code page and 
font Is valid to the printer device driver in its monitor output buffer. 
The printer device driver then returns the return code to the caller of 
the Verify Font lOCtl. 

If the spooler, or another monitor, is not registered the printer device 
driver will return the appropriate return code to the caller of the 
Verify Font lOCtl. 

Printer Device Driver interfaces 

The Interfaces required by the printer device driver for code page and 
font switching are: 

• Activate Font lOCtI - Category 5 Function 48h 

• Query Active Font lOCtI - Category 5 Function 69h 

• Verify Font lOCtI - Category 5 Function 6Ah 

• Font Monitor Buffer Commands 

- Activate Font 

- Query Active Font 

- Verify Font 

Font IMonitor Buffer Commands 

Printer A/lonltor Record: Each monitor record can be of variable 
length. However, there must be a word of flags at the beginning of 
each monitor record. The flags are defined as follows: 
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Monitor Flags 
ByteO 



7 6 5 4 3 2 1 0 



♦Reserved -I 



Open 
Close 

Flush 



Device Driver 
Dependent 

Byte 1 



7 6 5 4 



Reserved ' 



3 2 10 



Printer Code Page Monitor 
Buffer Command / Response 

Code Page 
Command Processed 

INT 17H Code Page Request 
Status 



When the Status bit is set to 1 (byte 1, bit 3), this indicates that the 
monitor buffer is a status paclcet from the printer device driver. In 
this case, the next six bytes are: 



Byte 2 and 3 



System File Number 


Byte 4 


Byte 5 


Status 


Reserved, Set to 0 


Byte 


6 and 7 


Reserved, Set to 0 



Byte 2 & 3 System File Number WORD 

Byte 4 Status byte which indicates the type of printer error. This 
will be the same 8 bits returned as the status field in a 
request header. 

Byte 5 Reserved, and must be set to zero (0). 

Byte 6 & 7 Reserved WORD, must be set to zero (0). 

When the Font Monitor Buffer command bit is set to 1 (byte 1, bit 0), 
this indicates that the monitor buffer is a Font Monitor Buffer 
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command or a response to a previous Font Monitor Buffer command. 
In this case, the next six bytes are: 



Byte 2 and 3 



System File Number 


Byte 4 


Bytes 


Command Byte 


Reserved, Set to 0 


Byte 


6 and 7 


Reserved, Set to 0 



Byte 2 & 3 System Fiie Number 

Byte 4 Font Monitor Buffer Command Byte which indicates the 
type of command or response. 

Byte 5 Reserved, and must be set to 0. 

Byte 6 & 7 Reserved WORD, must be set to 0. 

When the Code Page Command Processed bit is set to 1 (byte 1, 
bit 1), the Font Monitor Buffer command has been processed by the 
spooler. The printer device driver sends Font Monitor Buffer com- 
mands on monitor chain lndex=1. A monitor which services the Font 
Monitor Buffer command will use MonWrite to place the Font Monitor 
Buffer Response on Monitor chain Index = 2. Data to be printed con- 
tinues to flow on monitor chain lndex=1. Monitor chain Index = 2 is 
used only for the Font Monitor Buffer responses so that the printer 
device driver does not block a program issuing a code page and font 
lOCtI request when print data monitor buffers are already queued 
ahead of the lOCtI request. 

When the INT17H Code Page Request bit is set to 1 (byte 1, bit 2), the 
Activate Code Page Request was Issued automatically by the printer 
device driver on behalf of INT17H processing and the application is 
not waiting for a response. 

The valid Font Monitor Buffer commands, along with the remainder of 
the buffer contents for the responses, are as follows: 

Byte 4 01H Activate Font 
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Command Data, starting at byte 8: 



08 


WORD 


Return Code 


OA 


WORD 


Code Page 


OC 


WORD 


Font Id 



Return Code A WORD value starting at byte 8, and includes the fol- 
lowing values: 

• Successful completion 

• Code page and font switching not active 

• Unable to access specified font file 

• Unable to locate or activate specified code page 

• Unable to locate or activate specified font. 



Code Page The value of the code page to make the currently active 
code page. 

OOOOH If both the code page value and font ID are 

specified as 0, set printer to hardware default 
code page and font. 

0001H-FFFFH Valid code page numbers. 

Fontid The ID value of the font to make currently active. 

OOOOH If both the code page value and Font Id are 
specified as zero (0), set printer to hardware 
default code page and font. 

if only the font Id is specified as 0, any font 
within the specified code page is acceptable. 

0001H-FFFFH Valid font ID numbers, font types defined by 
the font file definitions. .* 

Remarks The Font Monitor Buffer command is passed on monitor 
chain index = 1 by the printer device driver to the spooler. 
The Font Monitor Buffer response is returned by the 
spooler on monitor chain index =2 to the printer device 
driver. 

Byte 4 = 02H Query Active Font 

There is no additional command data. 
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The response is as follows: 



08 


WORD 


Return Code 


OA 


WORD 


Code Page 


OC 


WORD 


Font Id 



Return Code A WORD value starting at byte 8, and includes the fol- 
lowing values: 

• Successful connpletlon 

• Code page and font switching not active. 

Code Page The value of the currently active code page. 

Valid numbers are between 0 and 65535. 

A value of 0 for both the code page and font ID Indicates 
that the hardware default code page and font is active. 

The ID value of the currently active font. 

Valid numbers are between 0 and 65535. 

The Font Monitor Buffer command is passed on monitor 
chain Index = 1 by the printer device driver to the spooler. 
The Font Monitor Buffer response is returned by the 
spooler on monitor chain index =2 to the printer device 
driver. 

Byte 4 - 03H Verify Font 

Command Data, starting at byte 8: 



Font Id 
Remarks 



Return Code A WORD value starting at byte 8, and includes the fol- 
lowing values: 

• Code page and font valid 

• Code page not valid 

• Font not valid 
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• Code page and font switching not active 

• Unable to access specified font file. 



Code Page Tlie value of the code page to validate. 

Values may be 0 to 65535. 

Fontid The Font ID to validate. 

Values may be 0 to 65535. A value of 0 Indicates that any 
font within the specified code page is acceptable. 

Remarks The Font Monitor Buffer command is passed on monitor 
chain index = 1 by the printer device driver to the spooler. 
The Font Monitor Buffer response Is returned by the 
spooler on monitor chain index = 2 to the printer device 
driver. Because the Activate Font may also contain data 
to be printed, it may also be returned by the spooler on 
monitor chain index=1. 
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Chapter 10. Functions and Utilities for 
Problem Determination 



Design Elements 

Reliability Functions 
Semaphores 

Semaphore mechanisms sequence the updating or processing of data 
by asynchronous operations. 

Dislcette processing 

OS/2 maintains an awareness of the volume label associated with 
each open file and an awareness of the volume label on the current 
diskette in each drive. You are instructed to insert the correct diskette 
whenever I/O is requested for a diskette which is not the current one. 
After you respond, OS/2 reads and compares the volume label to 
verify that the correct volume has been inserted. OS/2 then performs 
the requested I/O. This feature is supported for file I/O using file 
handles. 

File write-through 

Applications have the ability to know that a successful file write oper- 
ation has occurred in order to sequence file updates to minimize the 
impact of a system failure. This can be done with synchronous file 
I/O to synchronous files. The VERIFY command is available for vali- 
dating file updates. 
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Availability Functions 

The following Items help maximize system availability. They also can 
be used to improve reliability. 

Termination exit capability — Termination exits are provided. 

Error recovery — An application can attempt recovery from any error 
it detects. Upon detection of an error, the application can attempt to: 
retry, ignore, correct, or abort. 

Locailzation of Damage —Termination is done on a process basis. 
When an error occurs, and error recovery cannot be accomplished, 
only the affected process(es) are terminated. 

Serviceability Functions 

The following functions are provided for problem determination and 
isolation in a multitasking environment: 

Create Dump Dislcette Utility — Creates a diskette to be used with the 
stand-alone dump facility. This utility should be executed imme- 
diately following system installation. 

Note: This procedure (CREATEDD) is required only ONCE for each 
dump. It does not need to be done on every re-installation/re-start. 

System Trace Facility — Allows important system events to be 
recorded. 

Stand-alone Dump Facility — Initiated by pressing Ctrl/Alt/NumLock 
twice. 

Note: This procedure will require a system restart (re-boot) after the 
dump is complete. 
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System Trace Facility 



The OS/2 System Trace Facility helps support personnel in diag- 
nosing system problems. It provides an internal system interface that 
allows the placing of variable length data in a variable size circular 
trace buffer. This provides a historical trail of system events that 
could be useful in isolating the cause of a system failure. 

Using System Trace 

TRACEBUF and TRACE commands in CONFIG.SYS. 

There are two CONFIG.SYS commands used to indicate that system 
tracing is desired. The format of the commands follows: 

TRACEBUF = y 

where y is an integer that represents the size of the Circular Trace 
Buffer in 1K increments. 

• If the TRACEBUF' command Is invalid, the command is ignored 
and a 'TRACEBUF' will be allocated only if a 'TRACE' command 
is specified. 

• If this facility receives errors in trying to allocate the trace buffer 
and associated data, an error message will be reported and 
tracing will never be enabled. 

• if multiple 'TRACEBUF' commands are given, the last one super- 
sedes all previous occurrences. 

• If a 'TRACE' command is in the CONFIG.SYS file, but no valid 
'TRACEBUF' command is present, a 4K buffer is allocated. 

• If a TRACEBUF' command is In the CONFIG.SYS file, but no 
'TRACE' command is present, the buffer exists (if it could be allo- 
cated), but no trace events will be enabled during initialization. 

• If neither 'TRACEBUF' nor 'TRACE' appears in CONFIG.SYS, no 
trace buffer will be allocated and tracing will never be enabled. 

TRACE =(0N j OFF) [x [.x ...]] 

Where x is an integer that indicates whether an event is to be enabled 
(ON) or disabled (OFF) for system tracing, multiple events can be 
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individually selected by listing one after the other. The values of the 
numbers are between 0 and 255, and are referred to as major event 
codes. Examples of events associated with different major event 
codes are tasking events or hardware interrupts. 

• An invalid TRACE' command results in error message(s) and is 
ignored, if the command is invalid, the buffer Is allocated only If 
either TRACE' or 'TRACEBUF' is specified. 

• If no parameters are listed after the ON/OFF parameter, then ON 
indicates all trace calls encountered are traced and OFF means 
no tracing is done. 

• Multiple 'TRACE' commands are allowed In the CONFIG.SYS file. 

• If an event code is referenced in multiple 'TRACE' commands, the 
last reference supersedes all others. 

TRACE as an OS/2 Command Utility 

The OS/2 command utility 'TRACE' provides dynamic 
enabling/disabling of tracing by the user. This utility Is available only 
in the OS/2 mode. The format of the command is : 

[d:] [path] TRACE (ON ! OFF) [x [,x ...]] 

where x is a decimal integer between 0 and 255 Inclusive, corre- 
sponding to a major trace event code that is to be traced (ON) or not 
traced (OFF). 

• If no parameters are listed after the ON/OFF parameter, then ON 
indicates all trace calls encountered are traced and OFF means 
no tracing is done. 

• If no trace buffer was allocated during the processing of the 
CONFIG.SYS file at initialization time, an error message will 
result and no tracing Is provided by the system. 

• If a number is outside of the given range, an error message is 
generated for that number and processing of the remainder of the 
command continues. 

• If the ON/OFF parameter is invalid, or all of the major event 
codes are invalid, a message is generated and the entire 
command is ignored. 
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Considerations/Limitations 

The trace buffer is circular and wraps. In some cases, you may lose 
useful information if trace is not disabled (with TRACE OFF) imme- 
diately after the problem has occurred. 



Stand-Alone Dump Facility 

The Stand-Alone Dump facility aids In providing problem determi- 
nation services for OS/2. The OS/2 Stand-Alone Dump facility is used 
to dump to diskettes all physical memory, including the 640K - 1M 
address space. Memory between 640K and 1M contains information 
belonging to I/O adapters that have shared memory (display, smart 
communications adapters, and others). 

The major portion of the Stand-Alone Dump functions Independently 
of OS/2, although a portion of the Dump facility is part of the fixed and 
memory resident portion of OS/2. The purpose of the memory resi- 
dent code is to stabilize the system hardware and initiate the start of 
the Stand-alone Dump diskette. 

A keystroke sequence (Ctrl + Alt +NumLock pressed twice) is entered 
to invoke the stand-alone dump. That keystroke sequence is detected 
by the keyboard device driver and control Is passed to memory resi- 
dent stand-alone dump code. That code sets up the hardware so a 
start-up of a diskette can be done. It then starts a stand-alone dump 
diskette to initiate the actual dumping of physical memory. The 
stand-alone-dump diskette is created with the Create Dump Diskette 
Utility. The stand-alone dump will be analyzed by an IBM Customer 
Representative. 
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Initiating a Dump 



Procedure used to start a Dump 

To initiate a dump, press the NumLock key twice in a row while 
liolding the Ctrl + Alt keys down. The user should exercise caution 
when initiating a dump because system activities In progress will 
stop without cleanup. The Ctrl + Alt + NumLock keys may be used in 
either the OS/2 mode or the DOS mode. A prompt will instruct you to 
insert the stand-alone dump diskette in drive A. The dump code will 
verify that a CREATEDD diskette has been inserted in drive A. This is 
done to avoid an accidental start on a f jxed disk system by placing an 
incorrect diskette In drive A. 

From this point, all physical memory will be dumped to diskette(s). If 
additional diskettes are needed after the initial stand-alone dump 
diskette, then formatted diskettes can be used. Each time you are 
prompted to insert another diskette, you may end the memory dump 
by re-inserting the first dump diskette. 

If additional diskettes are required, a header record will be placed on 
each additional diskette. This header record also contains the 
summary information available at the time this diskette is loaded for 
dumping. After the dump has completed, a summary record will be 
written on the first stand-alone dump diskette. The summary record 
will contain, at a minimum, information pertaining to the range of 
physical memory dumped, the number of diskettes used in the dump, 
and the physical memory range that was placed on each diskette. 
Once the dump is complete, you need to re-start OS/2 In order to use 
OS/2 again. 
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Trace Formatter Utility 

The Trace Formatter Utility Is a service aid tliat can be used in con- 
junction with the system trace facility to debug problems in the OS/2 
system. The facility captures the current contents of the system trace 
buffer, analyzes each trace record, and displays the formatted data 
on the standard output device. The standard output device can be the 
display, a printer or a file. 

The format of the command is: 
[d:] [path] TRACEFMT 

[d:] [path] is the optional drive and path where the system can find 
the TRACEFMT utility. 

To use the trace formatter, a trace buffer must have been allocated at 
IPL time. To allocate a trace buffer, you must Include either the 
TRACEBUF or TRACE command In CONFIG.SYS. Tracing is not 
required to be active (that is, TRACE = ON) at the time the TRACEFMT 
command is issued. 

The trace formatter can be invoked as many times as required to 
diagnose the problem. 

The formatted trace records are displayed in reverse time-stamp 
order (that is, newest records first). Each formatted trace record con- 
sists of header Information and optional data. The header Informa- 
tion cental ns: 

• The title of the trace event. The title is a string describing the 
event. Each major/minor event code combination is converted to 
a unique title. 

• For events that have a pre-invocatlon and post-Invocation code, a 
string is displayed indicating whether the trace record Is the pre- 
invocation or post-invocation of the event. 



10-7 



• The issuing process ID in the form "Issuing Process ID=xxxx" 

• Two strings that represent the trace record flag word as follows: 

- "Kernel Call" or "Dynlink Call" to Indicate the type of call 
invocation 

- "OS/2 Mode" or "DOS Mode" to indicate the mode of the 
calling process 

• The time stamp of the event in the form "Time Stamp = ss.hh, 
where "ss" is seconds and "hh" is hundredths of seconds. If the 
time stamp is the same as the previous trace record, the time will 
not be displayed. Instead, the string "Time Stamp=...." is dis- 
played. 

Following the header information fields, the optional event specific 
data Is displayed. If unrecognized trace records have been added to 
the trace buffer, the trace formatter will display "Unrecognized Trace 
Event" as the event title, followed by the rest of the header data. It 
will then display the major and minor code contained in the trace 
record. 

An example formatted trace output appears below: 

DosHoldSignal Post-Invocation 

Issuing Process ID=G006 OS/2 Mode Kernel Call Time Stamp= 

Return Code=O000 

DosHoldSignal Pre-Invocation 

Issuing Process ID«0OO6 OS/2 Mode Kernel Call Time Stamps 

Action Code=0000 

DosGetShrSeg Post-Invocation 
Issuing Process 10=0006 OS/2 Mode Kernel Call Time Stamps.... 
Sel ector-0307 Return Code=0000 

DosGetShrSeg Pre-Invocation 
Issuing Process ID=0006 OS/2 Mode Kernel Call Time Stamp=23.44 
Name=\SHAREMEM\SMG\SGTITLE 
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Create Dump Diskette Utility 



This utility is used to create the initial, start (boot) diskette that con- 
tains the files necessary to perform the stand-alone dump. The 
dislcette is also made to appear full to prevent accidentaity placing 
data other than from the dump on the dislcette. If additional dump 
disl<ettes are needed for a given dump, use diskettes that were for- 
matted with the FAT based OS/2 FORMAT utility. 

You can only invoke this utility from the OS/2 mode of OS/2. 

Using the Create Dump Diskette Utiiity 

To invoke the Create Dump Diskette utility, enter the following: 

[d:] [path] CREATEDD x 

Where: 

[d:J [path] - is the optional drive and path where the CREATEDD utility 
can be found by the system. 

X - is the destination drive that contains the diskette to be used as the 
dump diskette. 

If no parameter or an an Invalid parameter is specified, the utility 
ends and no dump diskette is created. 

The CREATEDD utility calls the FORMAT utility. Therefore, FORMAT 
must reside in the Default Directory or the Path must be set up to find 
the FORMAT utility. 
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Chapter 11. Country Support 
Considerations 



Introduction 

Country Support for OS/2 includes these features: 

• Country dependent information 

• Country APIs 

• National Iceyboard layouts 

• Configuration commands 

• Translated system message files 

Country Dependent Information 

Country information is available in OS/2 for all the countries and cor- 
responding country codes listed below: 



Country Code 

United States 001 

Canada 002 

Latin America 003 

Netherlands 031 

Belgium 032 

France 033 

Spain 034 

Italy 039 

Switzerland 041 

United Kingdom 044 

Denmarl( 045 

Sweden 046 

Norway 047 
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Country 

Germany 
Australia 
Japan 
Korea 



Code 

049 
061 
081 
082 
086 
088 
099 
351 
358 
785 
972 



People's Republic of China 



Taiwan 
Asia 



Portugal 
Finland 
Arabic 
Hebrew 



For each country code there is a corresponding set of country 
dependent information contained in the COUNTRY.SYS file that 
includes: 

• Time and date format, currency symbol and decimal separator 
information 

• Lower to upper case mapping table for ASCII characters 

• Collating sequence table for ASCII character string sorting by 
SORT utility 

• DBCS environmental vector table for double-byte character sets. 

The set of country dependent information that is used by OS/2 is 
determined by the country code the COUNTRY command is set to in 
CONFIG.SYS. This system country code is always the same for all 
application sessions. Country information retrieval Is based on the 
country code and code page of the calling process or a selected 
country code and selected code page. 

Applications can request country information for the system country 
code used by OS/2 or a specific country code using the Country API 
calls: 

DosGetCtrylnfo - Get the time, date and other format information 
for the current country code or a selected country code. 

DosCaseMap - A variable length string of ASCII characters is 
case mapped from lower to upper case and returned. 

DosGetCollate - Get the collate sequence table for sorting 
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DosGetDBCSEv - Get the DBCS environment vector binary value 
ranges of valid lead bytes for double-byte characters. 

Please refer to Technical Reference, Vol. 2 for more detailed informa- 
tion about function calls and the format of the information returned. 



National Keyboard Layouts 

System keyboard layouts are available for different countries. The 
following table lists these different countries and the two-letter code 
that is used to select the desired keyboard layout with the KEYB 
utility: 



Keyboard Code 

Belgium BE 

Canadian-French CF 

Denmark DK 

Finland SU 

France FR 

Germany GR 

Italy IT 

Latin America LA 

Netherlands NL 

Norway NO 

Portugal PO 

Spain SP 

Sweden SV 

Swiss-French SF 

Swiss-German SG 

United Kingdom UK 

United States US 



The system keyboard layout is selected by the utility command KEYB 
and the same layout is used for all application sessions. Multiple 
KEYB commands can be selected by the user in a given session. The 
last keyboard layout selected determines the current keyboard layout 
in the system. The United States keyboard layout is the default 
layout. 

Note: This two-letter code is also used in the CONFIG.SYS 
DEVINFO= command. 
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Code Page Configuration 



Code page configuration of the system is necessary to be able to suc- 
cessfully switch between two code pages at run time. The following 
set of commands must be set up correctly in CONFIG.SYS for this 
purpose: 

Command Purpose 

CODEPAGE Specify one or two code page identifiers the system is 
to set up to use. 

COUNTRY Specify the country code and a fully specified file 

name. The file contains a set of country information 
characters encoded according to a code page based 
on ASCII. The system defaults to the COUNTRY.SYS 
file In the root directory of the start drive if no file is 
specified. 

DEVINFO Specify the keyboard layout selection and a fully 
specified file name. The file contains a keyboard 
layout table for translating keystrokes Into characters 
encoded according to a code page based on ASCII. 
The system defaults to the KEYBOARD.DCP file in the 
root directory of the boot drive if no file is specified. 

DEVINFO Specify for the display device a fully specified file 
name. The file contains a video font table for dis- 
playing characters encoded according to a code page 
based on ASCII. The system does not have a default 
file name but the file VIOTBL.DCP Is provided. 

DEVINFO Specify for the printer device a fully specified file 
name. The file contains a printer font table for 
printing characters encoded according to a code page 
based on ASCII. The system does not have a default 
file name but the files 4201. DCP and 5201. DCP are 
provided. 



Incorrect, partial, or mismatched set-up of commands for code page 
selections, country code, keyboard layout, display, and printer may 
cause ineffective switching between code pages at run time. See the 
User Reference for the description and syntax of each command and 
the CHOP change code page command. 
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utility and Configuration Command Support 



The configuration command COUNTRY lias the format 
COUNTRY = XXX where xxx is the country code for the country 
dependent information. This command causes the current country 
code to change from the system default (United States =001) to xxx. 

The various countries supported and their associated country codes 
are discussed earlier in this chapter. 

The CONFIG.SYS RUN= command can be used with the KEYB utility 
to start the system with a system keyboard layout other than the U.S. 
default. The KEYB [yy] utility is used to change the system keyboard 
layout. 

The OS/2 System Installation allows system installation for a selected 
country code and keyboard layout. 
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Appendix A. The Linker 



This appendix contains tlie following subjects: 

• Converting object files to executable code 

• Linl<er options 

• Linlcer error messages 

• Module definition file statements 

Note: The OS/2 Linker does not support the use of the APPEND 
command and will not find run time libraries in APPEND directories. 



Converting Object Files to Executable Code 



To convert object code files to executable code, the OS/2 Linker 
requires the following syntax: 

LINK object-1 i st . [run-f i 1 e] , [map-f i 1 e] , [1 i brary-1 i st] , 
[def i ni ti on-f i 1 e] , [/opti ons 1 i st] ; 

The preceding syntax has the following meaning: 

object-list A list of object files to be linked together. Sep- 

arate filenames with plus ( + ) signs or blanks. 
The default extension is .OBJ. 



[run-file] 



[map-file] 
[library-list] 

[definition-file] 
[/options list] 



The name of the file to receive the executable 
output. The default filename is the name of the 
first listed object file. The default extension is 
.EXE. 

The name of the file to receive the map listing. 

A list of libraries for LINK to search. Separate 
list items with plus ( + ) signs or blanks. The 
default extension is .LIB. 

An optional module definition file. 

An optional list of linker parameters. 



The commas (,) shown in the command line syntax are required if all 
the input fields are specified on a single line. If the command line 
does not end with a semicolon (;), the linker will prompt for any 
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remaining input fields not given on the command line or in a 
response file. 



Note: For furtiier information on iinl<ing, see Chapters 7 and 8 in the 
OS/2 Programmer's Guide. Those chapters explain: 

• How to link dynamic linl< libraries 

• How to use the linl<er by: 

- Responding to prompts 

- Typing on the command line 

- Creating an Automatic Response File (ARF). 



About LINK Options 

LINK can be used to link programs written with the IBM languages in 
either the OS/2 or DOS environments. The overlay capability is for 
use in the DOS 3.3 environment only. 

Using LINK Options 

The linker options control the tasks performed by LINK. You may 
specify an option anywhere before the last comma on the command 
or response line. Every option must begin with the slash character, 
even if other options appear before it on the line. 

You can abbreviate option names as long as your abbreviations 
contain enough letters to distinguish the specified option from other 
options. Minimum abbreviations are listed with the description for 
each option on the following pages. Link does not recognize spaces 
between characters, nor does it recognize transpositions (changes in 
order). The link options are: 

Option Description 

/ALIGNIMENT Sets segment alignment factor 

/CODEVIEW Includes debugging information for 



the CodeView debugger 



/CPARMAXALLOC 



Changes value of maximum number 
of reserved paragraphs 



/DOSSEG 



Forces ordering of segments 



/DSALLOCATE 



Controls data loading 
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/EXEPACK 

/FARCALLTRANSLATION 
/HELP 

/HIGH 

/INFORMATION 

/LINENUMBERS 
/MAP 

/NODEFAULTLIBRARYSEARCH 

/NOFARCALLTRANSLATION 

/NOGROUPASSOCIATION 

/NOIGNORECASE 

/NOPACKCODE 

/OVERLAYINTERRUPT 

/PACKCODE 

/PAUSE 

/SEGMENTS 

/STACK 
/WARNFIXUP 



Packs executable files 

Optimizes intra-segment far calls 

Writes a list of the available options 
to the screen 

Cohtrols loading the run file 

Displays information about the 
linking process 

Copies line numbers to the map file 

Lists all public symbols in your 
program 

Ignores default libraries 

Disables far call translations 

Provides compatibility with previous 
compiler versions 

Case sensitive 

Disables code segment packing 

Sets the overlay 

Packs code segments 

Pauses to change disks 

Sets the maximum number of seg- 
ments 

Sets the stack size 
Warns of incorrect offset 
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Entry of Numeric Parameters 



Numeric parameters on the linker options and in the module defi- 
nition statements can be entered in decimal, hexadecimal, or octal. 
The format follows the C language conventions. 



The C entry conventions are: 



Decimal 



Hexadecimal 



Octal 



Any number which begins with anything other 
than a 0 digit. For example: 1,65536,2084, 
234 

A number which must begin with Ox and 
contain 0 - 9, A - F. For example: OxFFF, 0x10 

Any number which begins with the digit 0 
which contains only the digits 0-7. For 
example: 010, 05000, 0777 
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Aligning Segments 
/ALIGNMENT 



This option directs LINK to set tlie segment alignment factor in tlie 
executable file to the number given, which must be a power of 2. The 
default alignment is 512. 

This option is valid only for code linked to run in the OS/2 environ- 
ment. 

Format 

/ALIGNMENT:ni/m&er 

The minimum abbreviation is /A. 

Remarks 

Aligning a segment means adjusting its address to the next address 
occurring on a specific boundary based on the alignment factor. The 
adjusted, or aligned, address will then be evenly divisible by the 
alignment factor. 

The number can be a hexadecimal, decimal, or octal number. 

/ALIGNMENT tells the linker to adjust the beginning of a segment to 
the next address boundary which matches the specified alignment 
factor. 
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Preparing Files for CodeView 
/CODEVIEW 

This option directs LINK to Include symbolic debugging information 
for CodeView in tlie output executable file. 

Format 

/CODEVIEW 

Tiie minimum abbreviation is /CO. 
Remarks 

/CODEVIEW cannot be used witii /EXEPACK. 
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Reserving Paragraph Space 
/CPARMAXALLOC 



This option aliows you to change the defauit value of the MAXALLOC 
field, which controls the maximum number of paragraphs reserved in 
storage for your program. A paragraph is defined as the smallest 
storage unit (16 bytes) addressable by a segment register. 

This option is valid only for code linl<ed to run in the DOS 3.3 environ- 
ment or in the DOS environment of OS/2. 

Format 

/CPARMAXALLOC:number 

The minimum abbreviation is /CP. 

Remarks 

The maximum number of paragraphs reserved for a program is deter- 
mined by the value of the MAXALLOC field at offset OCH in the EXE 
header. 

The default for the MAXALLOC field is 65535 (decimal), or 64K minus 
1. You can reset the default to any number between 1 and 65535 
(decimal, octal, or hexadecimal). Changing the number is helpful 
because: 

• Program efficiency is not increased by reserving all available 
storage. 

• You may need to run another program within your program and 
you need to reserve space for that program. 

If the value you specify is less than the computed value of MINALLOC 
(at offset OAH), the linker uses the value of MINALLOC instead. 
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Ordering Segments 
/DOSSEG 



The /DOSSEG option forces segments to be ordered according to tlie 
following rules: 

1. All segments wltfi a class name ending in CODE. 

2. All other segments outside of DGROUP. 

3. DGROUP segments in the following order: 

a. Any segments of class BEGDATA. (This class name is 
reserved for IBM use.) 

b. Any segments not of class BEGDATA, BSS, or STACK. 

c. Segments of class BSS. 

d. Segments of class STACK. 

Format 

/DOSSEG 

The minimum abbreviation is /DO. 
Remarks 

Linking with the standard IBM C runtime libraries automatically 
enables the /DOSSEG option by way of a comment record in the 
startup module. 

An additional effect of this option is that the linker inserts 16 bytes of 
NULLS in front of the segment named _TEXT, if present. This is nec- 
essary for C runtime library support. 
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Controlling Data Loading 
/DSALLOCATE 



By default, LINK loads all data starting at the low end of the data 
segment. At run time, LINK sets the DS (data segment) pointer to the 
lowest possible address to allow the entire data segment to be used. 

You can use the /DSALLOCATE option to tell LINK to load all data 
starting at the high end of the data segment. To do this, set the DS 
pointer at run time to the lowest data segment address that contains 
program data. 

This option is valid only for code liniced to run in the DOS 3.3 environ- 
ment or in the DOS environment of OS/2. 

Format 

/DSALLOCATE 

The minimum abbreviation is IDS. 
Remarks 

The /DSALLOCATE option is typically used with the /HIGH option to 
take advantage of unused storage within the data segment. You can 
reserve any available storage below the area specifically reserved 
for DGROUP, using the same DS pointer. 
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Packing Executable Files 
/EXEPACK 



This option directs LINK to remove sequences of repeated bytes (typi- 
cally nulls) and to optimize the load-time relocation table before cre- 
ating the DOS executable file. This option is valid only for code 
linked to run in DOS 3.3 or in the DOS mode of OS/2. 

OS/2 executable files are always compressed. 
Format 

/EXEPACK 

The minimum abbreviation is /E. 
Remarks 

Executable files linked with this option are usually smaller and load 
faster than files linked without this option. However, you cannot use 
symbolic debugging programs with packed files. 

The /EXEPACK option does not always save a significant amount of 
disk space and may sometimes increase file size. Programs that 
have a large number of load-time relocations (about 500 or more) or 
long streams of repeated characters are usually shorter if packed. 

/EXEPACK cannot be used with /CODEVIEW. 
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Optimizing Far Calls 
/FARCALLTRANSLATION 



This option directs LINK to optimize Intra-segment far caiis into tlie 
sequence 

NOP 

PUSH CS 

CALL NEAR address 

By default, tlie llnl<er does not perform tliis optimization. 

This option is valid only for code Wnked to run in the OS/2 environ- 
ment. 

Format 

/FARCALLTRANSLATION 

The minimum abbreviation is /FAR. 

Remarks 

In most medium and large model programs, this option will yield sig- 
nificant savings in executable size and load time. iHowever, there is a 
small chance that the linl^er, during this optimization, will mistakenly 
identify a byte with a value of 0x9a as a far call, when in fact it |s an 
assembled constant. Take care when using this option. 
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Viewing the Options List 
/HELP 



The /HELP option causes LINK to write a iist of the available options 
to the screen. This may be convenient if you need a reminder of the 
available options. Do not give a file name when using the /HELP 
option. 

Format 

/HELP 

The minimum abbreviation is /HE. 
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Controlling Run File Loading 

/HIGH 



The /HIGH option loads the run file as high as possible in storage 
without overlaying the transient portion of C0MMAND.COM. The 
C0MMAND.COM file occupies the highest area of storage when 
loaded and the run file as low as possible. 

Use the /HIGH option in association with the /DSALLOCATE option. 

This option is valid only for code linked to run in the DOS 3.3 environ- 
ment or in the DOS environment of OS/2. 

Format 

/HIGH 

The minimum abbreviation is /HI. 
Remarks 

The /HIGH option should not be used with programs written in C. 
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Displaying information about tiie Linidng Process 
/INFORIVIATION 



The /INFORMATION option directs the linker to display information 
about the linl<ing process, including the phase of linlcing and the full 
name of each module as it is processed. 

Format 

/INFORMATION 

The minimum abbreviation is /I. 
Remarks 

/INFORMATION is useful for debugging. 
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Copying Line Numbers to the IVlap File 

/LiNEISIUi^BERS 



The /LINENUMBERS option directs the linker to copy the starting 
address of each program source line to a map file. The starting 
address is the address of the first instruction that corresponds to the 
source line. 

Format 

/LINENUMBERS 

The minimum abbreviation is /LI. 
Remarks 

LINK copies the line number data only if you give a map file name in 
the LINK convmand line and only if the given object file has line 
number information. Line numbering is available in some high level 
languages. 

The Macro Assembler does not copy line number information to the 
object file. If an object file has no line number information, the linl<er 
ignores the /LINENUMBERS option. 

If you do not specify a map file in a LINK command, you can still use 
the /LINENUMBERS option to force the linl^er to create a map file. 
Just place the option at or before the List File prompt. LINK gives the 
forced map file the same file name as the first object file specified in 
the command and gives it the default extension .MAP. 
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Producing a Public Symbol Map 
/MAP 



The /MAP option causes LINK to produce a listing of all public 
symbols declared in your program. This list is copied to the map file 
created by the linker. 

Format 
/MAP [inumber] 

The minimum abbreviation is /M. 
Remarks 

The number parameter specifies the maximum number of public 
symbols that the linker can sort in the map file. If you give no 
number, the limit is 2048. Valid values are 1 through 32767. They can 
be specified in hex, decimal, or octal. 

Specifying a number also causes the public symbols to be sorted by 
address only and not by name, regardless of the number. If you want 
to reduce the size of your map files by removing the list sorted by 
name, link with /MAP followed by a small number, but large enough 
to accommodate the number of public symbols in your program. 

If you do not specify a map file in a LINK command, you can use the 
/MAP option to force the linker to create a map file. LINK gives the 
forced map file the same name as the first object file specified in the 
command and the default extension .MAP. 

For a complete description and examples of the listing file format, see 
"The Map File" in this appendix. 
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Ignoring Default Libraries 
/NODEFAULTLIBRARYSEARCH 



The /NODEFAULTLIBRARYSEARCH option directs tiie linl<er to ignore 
any library names it may find in an object file. A high-level language 
compiler may add a library name to an object file to ensure that a 
default set of libraries is linked with the program. Using this option 
bypasses these default libraries and lets you name the libraries you 
want by including them on the LINK command line. 

Format 

/NODEFAULTLIBRARYSEARCH 

The minimum abbreviation is /NOD. 
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Disabling Far Call Translations 
/NOFARCALLTRANSLATION 



This option directs LINK to disable translation of intra-segment far 
calls. This option is only valid for the OS/2 mode. 

Format 

/NOFARCALLTRANSLATION 

The minimum abbreviation is /NOF. 

Remarks 

This is the default (see FARCALLTRANSLATION). 
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Preserving Compatibility 
/NOGROUPASSOCIATION 



The /NOGROUPASSOCIATION option causes the linker to process a 
certain class of fix-up routines in a manner compatible with previous 
versions of the linker. This option is provided primarily for compat- 
ibility with previous versions of other IBM language compilers. 

This option is valid only for code linked to run in the DOS 3.3 environ- 
ment or in the DOS environment of OS/2. 

Format 

/NOGROUPASSOCIATION 

The minimum abbreviation is /NOG. 

Remarks 

The /NOGROUPASSOCIATION option should not be used with pro- 
grams written in C. 
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Preserving Lowercase 
/NOIGNORECASE 



The /NOIGNORECASE option directs LINK to treat uppercase and 
lowercase letters in symbol names as distinct letters. Normally, LINK 
considers uppercase and lowercase letters to be identical, treating 
the names TWO, Two, and two as the same. When you use the 
/NOIGNORECASE option, the linker treats TWO, Two, and two as dif- 
ferent names. 

Format 

/NOIGNORECASE 

The minimum abbreviation is /NOI. 

Remarks 

The /NOIGNORECASE option typically Is used with object files 
created by high-level language compilers. Some compilers treat 
uppercase and lowercase letters as distinct letters and assume that 
the linker does the same. 
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Not Packing Code Segments 
/NOPACKCODE 



This option directs LINK not to try to pack neigliboring logical code 
segments into one physical segment. 

This option is valid only for code linked to run in the OS/2 environ- 
ment. 



Format 

/NOPACKCODE: 

The minimum abbreviation is /NOP. 



Remarks 

/NOPACKCODE should be used to override the default, /PACKCODE. 

For more information on packing, see the /PACKCODE option and 
"Rules for Segment Packing" in this appendix. 
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Setting the Overlay Interrupt 
/OVERLAYINTERRUPT 



By default, the DOS interrupt number used for passing control to 
overlays is 3FH. The overlay interrupt option allows you to select a 
different interrupt number. 

This option is valid only for code liniced to run in the DOS 3.3 environ- 
ment or in the DOS environment of OS/2. 

Format 

/OVERLAYINTERRUPTrnumber 

The minimum abbreviation is 10. 

Remarks 

The number can be a decimal number from 0 to 255, an octal number 
from 0 to 0377, or a hexadecimal number from 0 to OxFF. Numbers 
that conflict with DOS interrupts are not prohibited, but IBM does not 
recommend their use. 
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Packing Code Segments 
/PACKCODE 



This option directs LINK to try to pacl< neighboring iogical code seg- 
ments into one physical segment. 

This option is vaiid only for code linlced to run in the OS/2 environ- 
ment. 

Format 

/PACKCODE:[pac^//m/f] 

The minimum abbreviation is /PAC. 

Remarks 

The option /PACKCODE is the default. The option /NOPACKCODE 
should be used to override /PACKCODE. 

The optional packlimit is the limit at which to stop packing. If no 
number is given, LINK uses 65530. For more information on packing, 
see "Rules for Segment Packing" in this appendix. 
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Pausing to Change Disks 
/PAUSE 



The PAUSE option causes LINK to pause before writing tlie execut- 
able file to disk so that you can change disl<s. 

Format 

/PAUSE 

The minimum abbreviation is /PAU. 
Remarics 

If you choose the /PAUSE option, the linker displays the following 
message before creating the run file: 

About to generate .EXE file 

Change diskette in drive letter and press Enter 

The letter is the proper drive name. This message appears after the 
linker has read data from the object files and library files and after it 
has written data to the map file, if one was specified. LINK resumes 
processing when you press Enter. After LINK writes the executable 
file to disk, the following message appears: 

Please replace original diskette 
In drive letter and press Enter 

Note: Do not remove the disk used for the temporary file, if one has 
been created. If the temporary disk message appears when 
you have specified the /PAUSE option, you should press Ctrl- 
Break to end the LINK session. Rearrange your files so that 
LINK can write the temporary file and the executable file to the 
same disk, then try again. 
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Setting the Maximum Number of Segments 

/SEGIWIENTS 



The /SEGMENTS option directs tlie linl<er to process no more than 
number segments per program. If it meets more than the given limit, 
the linker displays an error message and stops linking. The /SEG- 
MENTS option bypasses the default limit of 128 segments. 

Format 

/SEGMENTS:numder 

The minimum abbreviation is /SE. 

Remarks 

If you do not specify /SEGMENTS, the linker reserves enough storage 
space to process up to 128 segments. If your program has more than 
128 segments, you must set the segment limit higher to increase the 
number of segments LINK can process. Set the segment limit lower if 
you get the following LINK error message: 

Segment limit set too liigli 

The number can be any integer value in the range 1 to 3072. 
Example 

This example sets the segment limit to 192: 
LINK file/SE:192,,; 

The next example sets the segment limit to 255 (X' FF'): 
LINK moda+modb,run/SEGMENTS:Oxff ,ab,em+tnl ibfp; 
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Setting the Stack Size 
/STACK 



The /STACK option sets the program stack to the number of bytes 
given by size. The linl<er automatically calculates the stack size of a 
program, basing the stack size on the size of any stack segments 
given in the object files. If you specify /STACK, the linker uses the 
given size in place of any value it may have calculated. 

Format 

/STACK:s/ze 

The minimum abbreviation is /ST. 
Remarks 

The size can be any positive integer value in the range 1 to 65535. 

The stack size can also be changed with the STACKSIZE module defi- 
nition file statement. 

Example 

The first example sets the stack size to 512 bytes. 
LINK file/STACK:512..; 

The second example sets the stack size to 255 (XTF') bytes. 
LINK moda+modb , run/ST : OxFF , ab , \1 i b\start ; 

The final example sets the stack size to 24 (30 octal) bytes. 
LINK startup+fne/ST:030,,; 
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Warning of Incorrect Offset 
/WARNFIXUP 



The /WARNFIXUP option directs the iinl<er to issue a warning for each 
segment-relative fix up of location-type "offset," such that the 
segment is contained within a group but is not at the beginning of the 
group. The linlter will include th6 displacement of the segment from 
the group in determining the final value of the fix up, opposite to what 
happens with DOS 3.3 executables. 

Format 
/WARNFIXUP 

The minimum abbreviation is /W. 
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Advanced LINK Topics 



Moving or Discarding Application Code Segments Under 
OS/2 

OS/2 can move and discard application code segments, and move 
and swap data segments to take best advantage of storage. 

Note: If the application must use a local heap, you can reserve heap 
space at run time by using the OS/2 service DosReallocSeg to 
increase the size of the automatic data segment. The auto- 
matic data segment is the group of logical segments, defined 
with the IBM Macro Assembler pseudo-op GROUP, named 
DGROUP. 



Order of Segments 

LINK copies segments to the executable file in the same order that it 
meets them in the object files. This order is maintained throughout 
the program unless the linker finds two or more segments having the 
same class name. Segments having identical class names belong to 
the same class type and are copied to the executable files as contig- 
uous blocks. 

Combined Segments 

LINK uses combine types to tell if two or more segments that are 
sharing the same segment name should be one segment. The 
combine types are public, stack, common, and private. 

• If a segment Is combine type public, the linker combines it with 
any segments of the same name and class. When LINK combines 
segments, it makes the segments contiguous in storage; you can 
reach each address in the segments using an offset from one 
frame address. The result is the same as if the segments were 
defined as a whole in the source file. 

The linker preserves the align type of each segment in the com- 
bined segment. So, even though the individual segments 
compose a single, larger segment, the code and data in each 
segment retain the original align type of the segment. If LINK 
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tries to combine segments that total more tlian 64K bytes, it dis- 
plays an error message. 

• If a segment is combine type stack, the linl^er combines individual 
segments as it does for public combine types. A difference is 
that, for stack segments, LINK copies an initial stack-pointer 
value to the executable file. This stack-pointer value is the offset 
to the end of the first stack segment (or combined stack segment) 
that LINK meets. If you use the stack type for slack segments, 
you need not give instructions to load the segment into the SS 
register. 

• If a segment is combine type common, the linlcer combines it with 
any segments of the same name and class. When LINK combines 
common segments, it places the start of each segment at the 
same address. This creates a series of overlapping segments. 
The resulting combination segment has a length equal to the 
length of the longest individual segment. 

• LINK assigns a default combine type private to any segments with 
no explicit combine type definition in the source file. LINK does 
not combine private segments. 

Groups 

A group lets LINK address non-contiguous segments of various 
classes relative to the same frame address. When LINK addresses 
groups, it adjusts all storage references to items in the group relative 
to one frame address. 

Segments of a group need not be contiguous, belong to one class, or 
have the same combine type. All segments of the group must fit 
within 64K bytes of storage. For OS/2 mode executable objects, a 
group is synonymous with a OS/2 selector or a physical segment. 

Groups do not affect the order of loading segments. You must use 
class names and enter object files in the correct order to guarantee 
contiguous segments, if the group is smaller than 64K bytes of 
storage, LINK may place segments that are not part of the group in 
the same storage area. LINK does not specifically checl< that all seg- 
ments in a group fit within 64K of storage. If the segments are larger 
than the 64K byte maximum, the linker can produce a fix-up overffiow 
error. 
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A description of groups and defining groups is in tlie IBM Personal 
Computer Macro Assembler/2 Language Reference bool<. 

Fix ups 

Once tlie linker knows the starting address of eacli segment in a 
program and establisiies all segment combinations and groups, it can 
fix up any unresolved references to labels and variables. The linker 
computes an appropriate offset and segment address and replaces 
the temporary address values with the new values. 

the size of the value that LINK computes depends on the type of ref- 
erence. If LINK discovers an error in the anticipated size of the refer- 
ence, it displays a fix-up overflow error message. This happens, for 
example, when a program tries to use a 16-bit offset to address an 
instruction in a segment with a different frame address. It also occurs 
when the segments in a group do not fit within a single, 64K block of 
storage. 

LINK resolves four types of references: 

• Short 

• Near self-relative 

• Near segment-relative 

• Long. 

• A short reference occurs in JMP instructions that try to pass 
control to labeled instructions that ar'e in the same segment or 
group. The target instruction must be no longer than 128 bytes 
from the point of reference. The linker computes a signed, 8-bit 

. number for this short reference. It displays an error message if 
the target instruction belongs to a different segment or group (dif- 
ferent frame address). The linker also displays an error message 
if the distance from the frame address to the target is more than 
128 bytes in either direction. 

• A near self-relative reference occurs in instructions that get 
access to data relative to the same segment or group. The linker 
computes a 16-bit offset for this near self-relative reference. It 
displays an error message if the data resides in more than one 
segment or group. 

• A near segnlent-relatlve reference occurs in instructions that 
attempt to get access to data either in a specified segment or 
group, or relative to a specified segment register. LINK com- 
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putes a 16-bit offset for this near segment-relative reference. It 
displays an error message if the offset of the target within the 
specified frame is greater than 64K bytes or less than 0 bytes. 
LINK also displays an error message if LINK cannot address the 
beginning of the canonical frame of the target. 

• A long reference occurs in CALL instructions trying to access an 
instruction in another segment or group. LINK computes a 16-bit 
frame address and a 16-bit offset for this long reference. The 
linker displays an error message If the computed offset is greater 
than 64K or less than 0 bytes. The iinl^er also displays an error 
message if LINK cannot address the beginning of the canonical 
frame of the target. 

Rules for Segment Packing in LINK 

When the linker produces an OS/2 executable object, it can pack dis- 
tinct, adjacent segments into the same physical or file segment. 
Physical or file segments are represented by entries in the program 
segment table. The rules that LINK uses when packing segments 
follow: 

• The limit of the total size of a set of segments packed into a file 
segment is 64K. LINK starts a new file segment while packing 
segments into a file when the size of the file segment reaches 
64K. 

• LINK packs adjacent segments only into a file segment. 

• LINK packs segments in the same group into a file segment. 
LINK does not pack segments in different groups into a file 
segment. If a segment in one group occurs between segments in 
another group, an error occurs. 

• /PACKCODE is the default. /NOPACKCODE should be used to 
override the default. 

• If the segment type (CODE or DATA) is not the same in all the 
packed segments, LINK sets the file segment flags to NON- 
SHARED CODE. 

• If LINK packs any segments that have an attribute of NON- 
SHARED, it sets the file segment flags NONSHARED CODE. 

• If LINK packs any segments that are not ERONLY (execute/read 
only), it marks the entire file segment as not ERONLY. 
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• If LINK packs any segments that are PRELOAD, it designates the 
entire file segment as PRELOAD. 

The Map File 

The map file lists the names, load addresses, and lengths of all seg- 
ments in a program. It also lists the names and load addresses of 
any groups in the program, the program's start address, and mes- 
sages about any errors the linker encountered. If the /MAP LINK 
option is used, the map file lists the names and load addresses of all 
public symbols. 

In the map file for programs that execute in the OS/2 environment, 
segment information has the general form: 

PROGRAM_A 



Start Length Name Class 

0OO1:OQQG 02C24H _TEXT CODE 

0001:2C3G 025O2H EMULATOR TEXT CODE 

0001:5132 00000H C_ETEXT ~ ENDCODE 

0002:0000 00170H EMULATOR DATA FAR DATA 

0003:0000 00G36H NULL BEGDATA 

0003:0036 00708H DATA DATA 



The Start column shows the address of the first byte in the segment, 
in the form segment numbenoffset. The segment numbers are 
indexes to the segment table of the executable file, and start from 1. 
The Length column shows the length of the segment in bytes. The 
Name column shows the name of the segment, and the Class column 
shows the class name of the segment. 

Group information has the general form: 

Origin Group 
0003:0 DGROUP 

At the end of the listing file, the linker shows the address of the 
program entry point. 

Program entry point at 00O1:02A0 
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In the map file for programs that execute In the DOS environment, 
segment Information has the general form: 



Start 


Stop 


Length 


Name 


Class 


OOOOOH 


02B86H 


02B87H 


TEXT 


CODE 


02B90H 


05091H 


02502H 


EMUU\TOR_TEXT 


CODE 


05092H 


05092H 


00000H 


C ETEXT 


ENDCODE 


050A0H 


0520FH 


00170H 


EMULATOR DATA 


FAR DATA 


052 10H 


05245H 


00036H 


NULL 


BEGDATA 


05246H 


05761H 


0051CH 


DATA 


DATA 



The Start column shows the address of the first byte in the segment. 
The number shown Is the offset from the beginning of the program. 
This number is referred to as the frame number. The Stop column 
shows the address of the last byte in the segment. The Length column 
has the length of the segment in bytes. The Name column shows the 
name of the segment, and the Class column shows the class name of 
the segment. 

Group Information has the general form: 

Origin Group 
0521:0 DGROUP 

At the end of the listing file, the linker shows the address of the 
program entry point. 

Program entry point at 0O00:O2A0 

If you have specified the /MAP LINK option, the linl<er adds a public 
symbol list to the map file. Symbols are listed twice: once in alpha- 
betical order, second, in load address order This list has the general 
form shown in the following example. The form is the same for pro- 
grams that execute in either the OS/2 or DOS environments. For 
each symbol address, the number to the left of the colon (:) repres- 
ents a segment number for the programs that execute in the OS/2 
environment, and a frame number for programs that execute in the 
DOS environment. 
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Address 




Publics by Name 


OQ03:071A 




$i8_imp1 icit_exp 


oooQ , n7i Q 
UUOo :u/ io 




$i8_inpbas 




G0Q1:287C 




$i8_input 




0003:0719 




$i8_input_ws 




0001:0CF6 




$i8_output 




Address 




Publics 


by Value 


0000:0000 


Imp 


DOSWRITE 


(D0SCALLS.138) 


0000:0000 


Imp 


DOSDEVCONFIG 


(D0SCALLS.52) 


0000:0000 


Imp 


DOSEXIT 


(D0SCALLS.5) 


0001:0010 




_main 




0001:0180 




_countwords 




0001:0238 




_analyze 




0OO1:O2AO 




_astart 




0001:0368 




cintDIV 





The first three symbols shown in the example under Publics by Value 
are Imported public symbols and appear In map files created for pro- 
grams that run only In the OS/2 environment. 
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Linker Error Messages and Limits 

This section lists error messages produced by the IBM Linker. 

Fatal errors cause the linker to stop running. Fatal error messages 
have the following format: 



location: error Lixxx: message text 

Non-fatal errors indicate problems in the executable file. LINK 
produces the executable file (and sets the error bit in the header if for 
the OS/2 mode). Non-fatal error messages have the following format: 



location: error L2 xxx: message text 

Warnings indicate possible problems in the executable file. LINK 
produces the executable file (it does not set the error-bit in the 
header for the OS/2 mode). Warnings have the following format: 



location: error L4xxx: 
message text 

In these messages, location is the input file associated with the error, 
or LINK if there is not input file. If the input file is a module defi- 
nitions file, the line number will be Included, as shown below: 



foo.def(3): fatal error LI 030: 
missing internal name 

If the input file is an .OBJ or .LIB file and has a module name, the 
module name Is enclosed in parentheses, as shown in the following 
examples: 



SLIBC.LIBUile) 

MAIN.OBJ(maln.c) 

TEXT.OBJ 
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The following error messages may appear when you link object files 
with LINK. 

LI 001 option : option name ambiguous 

A unique option name does not appear after the option indicator 
(/). For example, the command 

LINK /N main; 

produces this error, because LINK cannot tell which of the three 
options beginning with the letter N is Intended. 

LI 002 option : unrecognized option name 

An unrecognized character followed the option indicator (/), as in 
the following example: 

LiNK /ABCDEF main; 

LI 003 option : MAP symboi iimit too higli 

The specified symbol limit value following the MAP option is 
greater than 32767, or there is not enough memory to increase 
the limit to the requested value. 

L1004 option : invaiid numeric vaiue 

An Incorrect value appeared for one of the linker options. For 
example, a character string is entered for an option that requires 
a numeric value. 

LI 005 option : pacicing iimit exceeds 65536 bytes 

The number following the /PACKCODE option is greater than 
65536. 

LI 006 option : stacic size exceeds 65534 bytes 

The size you specified for the stack in the /STACK option of the 
LINK command is more than 65534 bytes. 

LI 007 option : interrupt number exceeds 255 

You gave a number greater than 255 as a value for the 
/OVERLAYINTERRUPT option. 

LI 008 option : segment limit set too high 

The specified limit on the /SEGMENTS option is greater than 3072 
using the /SEGMENTS option. 

LI 009 option : CPARMAXALLOC : iliegai vaiue 

The number you specified in the /CPARMAXALLOC option is not 
in the range 1 to 65535. 
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LI 020 no object modules specified 

You did not specify any object-file names to the linker. 

LI 021 cannot nest response files 

A response file occurs within a response file. 

LI 022 response line too long 

A line in a response file is longer than 127 characters. 

L1023 terminated by user 

You entered Ctrl + C or Ctrl + Break. 

LI 024 nested right parentheses 

You typed the contents of an overlay incorrectly on the command 
line. 

LI 025 nested left parentheses 

You typed the contents of an overlay incorrectly on the command 
line. 

L1026 unmatched right parenthesis 

A right parenthesis is missing from the contents specification of 
an overlay on the command line. 

LI 027 unmatched left parenthesis 

A left parenthesis Is missing from the contents specification of an 
overlay on the command line. 

L1030 missing internal name 

In the module definitions file, when specifying an import by entry 
number, you must give an internal name, so the linker can iden- 
tify references to the import. 

LI 031 module description redefined 

In the module definitions file, a module description specified with 
the DESCRIPTION keyword is given more than once. 

LI 032 module name redefined 

In the module definitions file, the module name is defined more 
than once with the NAME or LIBRARY keyword. 

LI 040 too many exported entries 

An attempt is made to export more than 3072 names. 

L1041 resident-name table overflow 

The total length of all resident names, plus three bytes per name, 
is greater than 65534. 
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LI 042 nonresident-name table overflow 

The total length of all nonresident names, plus three bytes per 
name, is greater than 65534. 

L1043 relocation table overflow 

There are more than 65536 load-time relocations for a single 
segment. 

LI 044 imported-name table overflow 

The total length of all the imported names, plus one byte per 
name, is greater than 65534 bytes. 

L1045 too many TYPDEF records 

An object module contains more than 255 TYPDEF records. 
These records describe communal variables. This error can only 
appear with programs produced by compilers that support com- 
munal variables. 

LI 046 too many external symbols In one module 

An object module specifies more than the limit of 1023 external 
symbols. Break the module into smaller parts. 

LI 047 too many group, segment, and class names In one module 

The program contains too many group, segment, and class 
names. Reduce the number of groups, segments, or classes, and 
recreate the object files. 

LI 048 too many segments In one module 

An object module has more than 255 segments. Split the module 

or combine segments. 

L1049 too many segments 

The program has more than the maximum number of Segments. 
The SEGMENTS option specifies the maximum allowed number; 
the default Is 128. Relink using the /SEGMENTS option with an 
appropriate number of segments. 

LI 050 too many groups in one module 

The linker found more than 21 group definitions (GRPDEF) in a 
single module. Reduce the number of group definitions or split 
the module. 

LI 051 too many groups 

The program defines more than 20 groups, not counting 
□GROUP. Reduce the number of groups. 
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LI 052 too many libraries 

An attempt is made to link with more than 32 libraries. Combine 
libraries, or use modules that require fewer libraries. 

LI 053 symbol table overflow 

The program has more than 256K bytes of symbolic information, 
such as public, external, segment, group, class, and file names. 
Combine modules or segments and recreate the object files. 
Eliminate as many public symbols as possible. 

LI 054 requested segment iimit too higti 

The linker does not have enough memory to allocate tables 
describing the number of segments requested (the default is 128 
or the value specified with the /SEGMENTS option). Try linking 
again using the /SEGMENTS option to select a smaller number of 
segments (for example, use 64 if the default was used previ- 
ously), or free some memory by eliminating resident programs or 
shells. 

LI 056 too many overlays 

The program defines more than 63 overlays. 

LI 057 data record too large 

A LEDATA record (in an object module) contained more than 1024 
bytes of data. This is a translator (compiler or assembler) error. 
Note which translator (compiler or assembler) produced the 
incorrect object module and the circumstances, and contact your 
authorized IBM Personal Computer dealer. 

L1070 segment size exceeds 64K 

A single segment contains more than 64K bytes of code or data. 
Try compiling, or assembling, and linking using the large model. 

LI 071 segment _TEXT iarger than 65520 bytes 

This error is likely to occur only In small-model C programs, but it 
can occur when any program with a segment named _TEXT is 
linked using the /DOSSEG option of the LINK command. Small- 
model C programs must reserve code addresses 0 and 1; this is 
increased to 16 for alignment purposes. 

L1072 common area longer than 65536 bytes 

The program has more than 64K bytes of communal variables. 
This error cannot appear with object files produced by the IBM 
Macro Assembler. It occurs only with programs produced by IBM 
C or other compilers that support communal variables. 
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LI 073 file-segment limit exceeded 

There are more than 255 physical or file segments. 

L1074 name : group larger than 64K bytes 

A group contained segments which total more than 65536 bytes. 

LI 075 entry table larger than 65535 bytes 

Because of an excessive number of entry names, you have 
exceeded a linker table size limit. Reduce the number of names 
in the modules you are linking. 

LI 080 cannot open list file 

The disk or the root directory is full. Delete or move files to make 
space. 

LI 081 out of space for run file 

The disk on which .EXE file is being written is full. Free more 
space on the disk and restart the linker. 

L1 082 stub .EXE file not found 

The stub file specified in the module definitions file is not found. 

LI 083 cannot open run file 

The disk or the root directory is full. Delete or move files to make 

space. 

LI 084 cannot create temporary file 

The disk or root directory is full. Free more space in the directory 
and restart the linker. 

L1085 cannot open temporary file 

The disk or the root directory is full. Delete or move files to make 
space. 

L1086 scratch file missing 

Internal error. You should note the conditions when the error 
occurs and contact your authorized IBM Personal Computer 
dealer. 

LI 087 unexpected end-of-flle on scratch file 

The disk with the temporary linker-output file is removed. 

L1088 out of space for list file 

The disk on which the listing file is being written is full. Free 
more space on the disk and restart the linker. 
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LI 089 filename : cannot open response file 

The linker could not find the specified response file. This usually 
indicates a typing error. 

LI 090 cannot reopen list file 

The original disk is not replaced at the prompt. Restart the linker. 

LI 091 unexpected end-of-file on library 

The disk containing the library probably was removed. Replace 
the disk containing the library and run the linker again. 

LI 092 cannot open module definitions file 

The specified module definitions file cannot be opened. 

L1 1 00 stub .EXE file Invalid 

The stub file specified in the definitions file is not a valid .EXE 
file. 

L1 101 invalid object module 

One of the object modules is non-valid. If the error persists after 
recompiling, contact your authorized IBM Personal Computer 
dealer. 

L1 102 unexpected end-of-file 

A non-valid format for a library was found. 

L1 1 03 attempt to access data outside segment bounds 

A data record in an object module specified data extending 
beyond the end of a segment. This is a translator error. Note 
which translator (compiler or assembler) produced the incorrect 
object module and the circumstances, and contact your author- 
ized IBM Personal Computer dealer. 

L1 104 filename : not valid library 

The specified file is not a valid library file. This error causes the 
linker to stop running. 

L1 1 1 0 DosAliocHuge failed 

Internal error. You should note the conditions when the error 
occurs and contact your authorized IBM Personal Computer 
dealer. 

L1 1 1 1 DosReallocHuge failed 

Internal error. You should note the conditions when the error 
occurs and contact your authorized IBM Personal Computer 
dealer. 
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L1112 DosGetHugeShift failed 

Internal error. You should note the conditions when the error 
occurs and contact your authorized IBM Personal Computer 
dealer. 

L1 11 3 unresolved COMDEF; Internal error 

You should note the conditions when the error occurs and contact 
your authorized IBM Personal Computer dealer. 

L1 1 14 file not suitable for /EXEPACK; relink without 

For the linked program, the size of the packed load image plus 
the packing overhead is larger than that of the unpacked load 
image. Relink without the EXEPACK option. 

L2000 imported entry point 

A MODEND, or starting address record, referred to an imported 
name. Imported program-starting addresses are not supported. 

L2001 fix up(s) without data 

A FIXUP record occurred without a data record immediately pre- 
ceding it. This is probably a compiler error. Note the conditions 
and contact an authorized service coordinator. 

L2002 fix up overflow near number in frame seg segname target 
seg segname target offset number 
The following conditions can cause this error: 

• A group is larger than 64K bytes. 

• The program contains an intersegment short jump or Interseg- 
ment short call. 

• The name of a data item in the program conflicts with that of a 
subroutine In a library included in the link. 

• An EXTRN declaration in an assembler-language source file 
appeared inside the body of a segment. 

For example: 

code SEGMENT public 'CODE' 

EXTRN main: far 
start PROC far 

call main 

ret 

start ENDP 
code ENDS 

The following construction is preferred: 



A-42 



EXTRN main: far 
code SEGMENT public 'CODE' 
start PROC far 

ca11 main 

ret 

start ENDP 
code ENDS 

Revise the source file and recreate the object file. 

L2003 intersegment self-relative fix up 

An intersegnnent self-relative fix up is not allowed. 

L2004 LOBYTE-type fix up overflow 

A LOBYTE fix up produced an address overflow. 

L2005 fix up type unsupported 

A fix up type occurred that is not supported by the linker. This is 
probably a compiler error. You should note the conditions when 
the error occurs and contact your authorized IBM Personal Com- 
puter dealer. 

L2010 too many fix ups In LID ATA record 

There are more fix ups applying to a LIDATA record than will fit in 
the linker's 1024-byte buffer. The buffer is divided between the 
data in the LIDATA record itself and run-time relocation items, 
which are 8 bytes apiece, so the maximum varies from 0 to 128. 
This is probably a compiler error. 

L2011 name : NEAR/HUGE conflict 

Conflicting NEAR and HUGE attributes are given for a communal 
variable. This error can occur only with programs produced by 
compilers that support communal variables. 

L2012 name : array-element size mismatcli 

A far communal array is declared with two or more different 
array-element sizes (for example, an array declared once as an 
array of characters and once as an array of real numbers). This 
error cannot occur with object files produced by the IBM Macro 
Assembler. It occurs only with IBM C and other compilers that 
support far communal arrays. 

L2013 LIDATA record too large 

A LIDATA record in an object module contains more than 512 
bytes of data. Most likely, an assembly module contains a very 
complex structure definition or a series of deeply-nested DUP 
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operators. For example, the following structure definition causes 
this error: 

alpha DB 10DUP(11 DUP(12 DUP{13 DUP{. . .)))) 

Simplify the structure definition and reassemble. (LIDATA Is a 
DOS term.) 

L2020 no automatic data segment 

No group named DGROUP is declared. 

L2021 library Instance data not supported in tlie DOS mode 

The library module is directed to have instance data. This works 
in the OS/2 mode only. 

L2022 name alias internal name: export undefined 

A name is directed to be exported but is not defined anywhere. 

L2023 name alias internal name: export imported 

An Imported name Is directed to be exported. 

L2024 name : symbol already defined 

One of the special overlay symbols required for overlay support 
is defined by an object. 

L2025 name symbol defined more than once 

Remove the extra symbol definition from the object file. 

L2026 multiple definitions for entry ordinal number 

More than one entry point name is assigned to the same ordinal. 

L2027 name : ordinal too large for export 

You tried to export more than 3072 names. 

L2028 automatic data segment plus heap exceeds 64K 

The size of DGROUP near data plus requested heap size is 
greater than 64K. 

L2029 unresolved externals 

One or more symbols are declared to be external in one or more 
modules, but they are not publicly defined in any of the modules 
or libraries. A list of the unresolved external references appears 
after the message, as shown in the following example: 

_exit in file(s) 

main.obj (main.c) 
_fopen in files{s) 

fileio.obj(fileio.c) main.obj (main.c) 

The name that comes before in flle(s) is the unresolved external 
symbol. On the next line is a list of object modules which have 
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made references to this symbol. This message and the list are 
also written to the map file, if one exists. 

L2030 starting address not code (using class 'CODE') 

You specified a starting address to the linker which is a segment 
that is not a CODE segment. Reclassify the segment to CODE, or 
correct the starting point. 

L4001 frame-relative fix up, frame ignored 

A fix up occurred with a frame segment different from the target 
segment where either the frame or the target segment is not 
absolute. Such a fix up is meaningless in the OS/2 mode, so the 
target segment is assumed for the frame segment. 

L4002 frame-reiative absoiute fix up 

A fix up occurred with a frame segment different from the target 
segment where both frame and target segments were absolute. 
This fix up is processed using base-offset arithmetic, but the 
warning is issued because the fix up may not be valid In OS/2 
environment. 

L4010 invaiid alignment specification 

The number following the /ALIGNMENT option is not a power of 2, 
or is not in numerical form. 

L4011 PACKCODE value exceeding 65500 unreliable 

Code segments of length 65501-65536 may be unreliable on the 
80286 processor. 

L401 2 ioad-iiigh disables EXEP ACK 

The options /HIGH and /EXEPACK are mutually exclusive. 

L4013 Invalid option for new-format executable file ignored 

If an OS/2 environment program is being produced, the options 
/CPARMAXALLOC, /DSALLOCATE, /EXEPACK. 
/NOGROUPASSOCIATION, and /OVERLAYINTERRUPT are mean- 
ingless, and the llnl^er ignores them. 

L4014 invaiid option for old-format executable file ignored 

If an OS/2 format program is produced, the options /ALIGNMENT, 
/NOFARCALLTRANSLATION, and /PACKCODE are meaningless, 
and the linker ignores them. 

L4020 name : code-segment size exceeds 65500 

Code segments of length 65501-65536 may be unreliable on the 
80286 processor. 
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L4021 no stack segment 

The program does not contain a stack segment defined with 
STACK combine type. This message should not appear for 
modules compiled with the IBM C/2 Compiler but it could appear 
for an assembler-language module. Normally, every program 
should have a stack segment with the combine type specified as 
STACK. You can ignore this message if you have a specific 
reason for not defining a stack or for defining one without the 
STACK combine type. 

L4022 n^mel, name2 : groups overlap 

Two groups are defined such that one starts in the middle of 
another. This may occur if you defined segments in a module 
definitions file or assembly file and did not correctly order the 
segments by class. 

L4023 exportname : export Internal-name conflict 

An exported name, or its associated internal name, conflict with 
an already-defined public symbol. 

L4024 name : multiple definitions for export name 

The name name is exported more than once with different 
internal names. All internal names except the first are ignored. 

L4025 A7ame : import internal-name conflict 

An imported name, or its associated internal name, is also 
defined as an exported name. The import name is ignored. The 
conflict may come from a definition in either the module definition 
file or an object file. 

L4026 modulename : self-imported 

The module definitions file directed that a name be imported from 
the module being produced. 

L4027 name : multiple definitions for import internai-name 

An imported name, or its associated internal name, is imported 
more than once. The imported name is ignored after the first 
mention. 

L4028 name : segment already defined 

A segment Is defined more than once with the same name in the 
module definitions file. Segments must have unique names for 
the linker. All definitions with the same name after the first are 
ignored. 
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L4029 name : DGROUP segment converted to type data 

A segment which is a member of DGROUP is defined as type 
CODE in a module definition file or object file. This probably hap- 
pened because a CLASS keyword in a SEGMENTS statement is 
not given. 

L4030 name : segment attributes changed to conform with auto- 
matic data segment 

The segment named name is defined in DGROUP, but the shared 
attribute Is in conflict with the instance attribute. For example, 
the shared attribute Is NONSHARED and the instance Is SINGLE, 
or the shared attribute is SHARED and the instance attribute is 
MULTIPLE. The bad segment is forced to have the right shared 
attribute and the link continues. The Image is not marked as 
having errors. 

L4031 name : segment declared In more than one group 

A segment is declared to be a member of two different groups. 
Correct the source file and recreate the object files. 

L4032 name : code-group size exceeds 65500 bytes 

Code segments of length 65501-65536 may be unreliable on the 
80286 processor. 

L4034 more than 239 overiay segments; extra put In root 

You specified an overlay structure containing more than 239 seg- 
ments. The extra segments have been assigned to the root 
overlay. 

L4036 no automatic data segment 

The program or dynalink library did not define a group named 
DGROUP, which is recognized by the linker as the automatic data 
segment. 

L4040 NON-CONFiRMING : obsolete 

In the module definitions file, NON-CONFORMING is a valid 
keyword for earlier versions of LINK and is now obsolete. 

L4041 HUGE segments not yet supported 

This feature is not implemented in the linker. 

L4042 cannot open old version 

An old version of the EXE file, specified with the OLD keyword in 
the module definitions file, could not be opened. 
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L4043 old version not segmented-executable format 

The old version of the .EXE file, specified with the OLD keyword 
in the module definitions file, does not conform to segmented- 
executable format. 

L4050 too many public symbols 

The /MAP option is used to request a sorted listing of public 
symbols in the map file, but there were too many symbols to sort 
(the default is 2048 symbols). The linker produces an unsorted 
listing of the public symbols. Relink using /MAP.number. 

L4051 filename : cannot find library 

The linker could not find the specified file. Enter a new file name, 
a new path specification, or both. 

L4053 VM.TMP : illegal file name; ignored 

VM.TMP appears as an object-file name. Rename the file and 
rerun the linker. 

L4054 filename : cannot find file 

The linker could not find the specified file. Enter a new file name, 
a new path specification, or both. 
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Linker Limits 



The table below summarizes the limits imposed by the linker. If you 
find one of these limits, adjust your program so the linker can accom 
modate it. 



Item 

■ twill 


Limit 


Symbol table 


256K 


Load-time relocations 
(for OS/2 programs) 


Default is 32K. If /EXEPACK is used, 
the maximum is 512K. 


Public symbols 


The range 7700-8700 can be used as a 
guideline for the maximum number of 
Dublic svmbols allowed* the actual 
maximum depends on the program. 


External symbols per 
module 


1023 


Groups 


Maximum number is 21, but the linker 
alwavs defined DGROUP so the effec- 
five maximum is 20. 


Over lavs 


63 


Seaments 


128 bv default' however this maximum 
can be set as high as 3072 by using the 
/SEGMENTS option of the LINK 
command. 


Libraries 


32 


Group definitions per 
module 


21 


Segments per module 


255 


Stack 


64K 
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Module Definition File Statements 



Notes: 

1. Any line in the module definition file preceded by a semi-colon (;) 
is considered a comment. The linker ignores them. 

2. The module definition file statement keywords must be in upper- 
case. 

Statement Description 

CODE Defines default attributes for code segments 

DATA Defines default attributes for data segments 

DESCRIPTION inserts text Into a program module 

EXPORTS Defines exported functions from dynamic link 

libraries 

HEAPSIZE Defines heap size in bytes 

ilMPORTS Defines imported functions from dynamic link 

libraries 

LIBRARY Declares a dynamic link library 

NAME Declares a program module 

OLD Directs preservation of earlier ordinals 

PROTMODE Declares program to run in the OS/2 mode only 

SEGR/IENTS Defines attributes for code and data segments on 

a per segment basis 

STACKSIZE Defines stack size in bytes 

STUB Appends DOS executable file to the OS/2 

program module 
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CODE 

Defines the default attributes for code segments 



Purpose 

Defines a default attribute for code segments within a program 
module. The default attributes of individual segments can be over- 
ridden using the SEGMENTS statement. 

Format 

CODE load executeonly iopi 
Remarks 

load (optional) A keyword which specifies when a segment 

is to be loaded. Specify one of the following: 

PRELOAD Load segment immediately. 

LOADONCALL (default) Load segment on demand. 

executeonly (optional) A keyword which specifies the access rights 
to code segments. Specify one of the following: 

EXECUTEONLY Sets access rights to execute only. 

EXECUTEREAD (default) Sets access rights to execute 
or read. 

lopi (optional) The keyword lopi specifies whether or not 

code segments have I/O privilege. 

lOPL Code segments have I/O privilege. 

NOIOPL (default) Code segments do not have I/O privi- 
lege. 

Example 

CODE PRELOAD lOPL 
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DATA 

Defines the default attributes for data segments 



Purpose 

Defines default attributes for data segments within a program 
module. All data segments are movable and swappable. With the 
exception of data segments specified with the option NONSHARED, 
the data segments in a dynamic linic module are shared across all 
dynamic Wnk modules in the library. 

The default attributes of individual segments can be overridden using 
the SEGMENTS statement. 

Format 

DATA load readonly Instance lopi shared 
Remarks 

load (optional) A keyword which specifies when a segment is to 
be loaded. Specify one of the following: 

PRELOAD Load segment immediately. 

LOADONCALL (default) Load segment on demand. 

readonly (optional) A keyword which specifies the access rights to 
data segments. 

READONLY Sets access rights to read only. 

READWRITE (default) Sets access rights to read or write. 

Instance (optional) A keyword which defines how the automatic 
data segment, that is, the physical segment represented 
by DGROUP, Is to be shared. Specify one of the following: 

NONE Specifies that there is to be no automatic data 
segment. 

SINGLE Specifies that the automatic data segment is to be 
shared by all instances of the module. This option is 
valid only for dynamic link libraries. 

MULTIPLE Specifies that the automatic data segment is to 
be copied for each instance of the module. 
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DATA 

Defines the default attributes for data segments 



Default: MULTIPLE for program modules and SINGLE for 
dynamic link libraries. 

The linker ensures that the automatic data segment attri- 
bute specified by SINGLE or MULTIPLE matches the 
default sharing attribute of all data segments. By default, 
DATA SINGLE forces shared data. By default, DATA MUL- 
TIPLE forces nonshared data. Similarly, DATA SHARED 
forces DATA SINGLE; DATA NONSHARED forces DATA 
MULTIPLE. 

If you specify contradictory statements such as DATA 
SINGLE and NONSHARED, the instance option will control 
the automatic data segment only. In this example, the 
automatic data segment is shared and all other data seg- 
ments are nonshared. 

iopi (optional) The keyword iopi specifies whether or not data 
segments have I/O privilege. 

lOPL Data segments have I/O privilege. 

NOIOPL (default) Data segments do not have I/O privilege. 

shared (optional) Specifies whether or not a unique copy of the 
READWRITE data segments should be loaded for each 
process using a dynamic link library. You can specify the 
following values: 

SHARED A single copy of each data segment is loaded. 
The copy is shared by all processes using the 
dynamic link library. 

NONSHARED A unique copy of each READWRITE data 
segment is loaded for each process using the 
dynamic link library. 

Default: NONSHARED for program modules and SHARED 
for dynamic link libraries. 



Example 

DATA SHARED READONLY PRELOAD 
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DESCRIPTION 

Inserts text into a program module 



Purpose 

Inserts text, such as source control Information or copyright informa- 
tion, into a program module. 

Format 

DESCRIPTION 'text' 
Remarks 

'text' A one line string of ASCII characters enclosed in single 

quotation marlcs. 

Example 

DESCRIPTION 'Calendar, Version 1.00' 



A-54 



EXPORTS 

Defines exported functions from dynamic iinic 

libraries 



Purpose 

Defines the names and attributes (functions) in the dynamic link 
libraries which are to be exported. The EXPORTS statement pre- 
cedes the definitions. You can specify as many as 3072 export defi- 
nitions, each on a separate line, after the EXPORTS statement. You 
must specify an export definition for every function In a dynamic link 
library. 



Format 

EXPORTS exportname =/nferna/name ordinal res iopl-parmwords 



Remarks 

exportname One or more ASCII characters which define the func- 
tion name to be used by applications to access the 

exported function. 

internalname (optional) Defines the actual name of the function in 
the dynamic link library. 

ordinal (optional) An integer number which specifies the func- 

tion's ordinal position within the dynamic link entry 
table. It is specified as @ordinal, where ordinal is the 
Integer position number. If specified, the entrypoint 
can be called by either name or ordinal. 

res (optional) The keyword RESIDENTNAME specifies that 

the function's entry points should be kept resident in 
memory. Use this option only if you specified the 
ordinal option. If the call is by entry point rather than 
by ordinal, frequently used entry points keep resident 
in memory enables OS/2 to resolve calls more rapidly. 

iopl-parmwords (optional) A numeric value which you must specify 
for functions executing with I/O privilege. A function 
which executes with I/O privilege is allocated a 
512-byte stack. When the function is called, the 
number of parameters (words) specified by lopl- 
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EXPORTS 

Defines exported functions from dynamic linic 
iibraries 

parmwords is copied from the caller's stack to the new 
stack. 

Although the EXPORTS statement is normally used to Identify func- 
tions in dynamic link libraries, the statement is also used for func- 
tions within program modules which execute with I/O privilege. When 
this Is the case, the only valid arguments are exportname (to identify 
the function within the application) and iopl-parm words. 

Example 

EXPORTS 

Sampi eRead 

StringIn=IntStnngIn 
ScreenOut 6 

Chariest @3 RESIDENTNAME 
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HEAPSIZE 
Defines heap size in bytes 



Purpose 

Defines the number of bytes an application needs for its local heap. 

Format 

HEAPSIZE bytes 

Remarks 

bytes An (integer) number which specifies the local 

heap size in bytes. 

Example 

HEAPSIZE 8000 
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IMPORTS 

Defines functions imported from dynamic linic 
libraries 



Purpose 

Defines the names of functions to be imported from dynamic lin!< 
libraries. External references to dynamic link libraries generally are 
resolved by specifying the .LIB files for the dynamic linl< library to the 
linker. The IMPORTS statement is an alternate method of resolving 
external references to dynamic link libraries. IMPORTS must 
precede the definitions. Specify each definition on a separate line. 

Format 

IMPORTS /nferna/name = libraryname.entry 
Remarks 

internalname (optional) Specifies the name used by the application to 
call the function being Imported, internalname is a unique 
name comprised of one or more ASCII characters. 

iibraryname The name of the dynamic link library which contains the 
function. 

entry The name of the function to be imported. It can be either 
of the following: 

.entryname The name of the function as It appears in the 
dynamic link library. 

.entryordlnal The ordinal value of the function. The 

ordinal value corresponds to the entry point 
in the dynamic link library. 

You can import OS/2 functions in the DOSCALLS library 
only by using .entryordlnal. 

Note: .entryname references to DOSCALLS are not sup- 
ported and will fail during the module load. Therefore, 
rather than directly importing OS/2 functions, link with 
DOSCALLS.LIB. 
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IMPORTS 

Defines functions imported from dynamic iinic 

libraries 



Example 

IMPORTS 

Sample.SampleWrite 
Read=Samp1 e . Sampi eRead 
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LIBRARY 

Declares a dynamic link library 



Purpose 

Specifies that the executable file being created is a dynamic link 
library. It also specifies the type of library initialization required for 
the library. 

Note: The LIBRARY statement tells LINK to build a dynamic link 
library. Do not associate the LIBRARY statement with .LIB files which 
are libraries of object modules. 

Format 

LIBRARY library name initialization-type 
Remarlcs 

libraryname (optional) Defines the name of the dynamic link library. 
After a dynamic link library has been loaded, 
libraryname is the name known to OS/2. The 
libraryname is not normally specified. The 
libraryname can be up to eight characters. 

Use caution when specifying a libraryname that differs 
from the filename of the .DLL being created. Subse- 
quent load requests, in the process of determining 
whether a .DLL has already been loaded, will recog- 
nize only this libraryname as the name of the loaded 
dynamic link library. 

Default: The executable filename, not including the 
extension. 

initialization-type (optional) Keyword specifying the type of library 
initialization required by the library module. This 
keyword is ignored if a library initialization routine is 
not defined for the library module. It must be one of 
the following: 

• INITGLOBAL - called only once when the library 
module is loaded initially. 

• INITINSTANCE - called once for each process 
which gains access to the library module. 
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LIBRARY 

Declares a dynamic link library 



Default: INITGLOBAL 

When the dynamic link module is loaded, It (optionally) can call an 
initialization routine before calling the dynamic Wnk library. See 
"Program Execution Control" on page 4-26 for additional information. 

Specify either the NAME statement or the LIBRARY statement. You 
cannot specify both. If neither NAME nor LIBRARY is specified, the 
default is NAME. If you use the LIBRARY statement, it must be the 
first statement in the module definition file. 

Example 

LIBRARY MatliCall 
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NAME 

Declares a program module 



Purpose 

Specifies that the executable file being created is a program module. 
Format 

NAME modulename 
Remarks 

modulename (Optional) Defines the name of the program module. 

After a program module has been loaded, the name 
known to OS/2 is the modulename, which can have up 
to eight characters. The modulename is not normally 
specified. 

Default: The executable filename, not including the 
extension. 

Remarks 

Specify either the NAME statement or the LIBRARY statement. You 
cannot specify both. If neither NAME nor LIBRARY is specified, the 
default is NAME. If you use the NAME statement, it must be the first 
statement in the module definition file. 

Example 

NAME Calendar 
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OLD 

Specifies previous version off a dynamic linic 

module 



Purpose 

Directs the linker to use export ordinals from the specified dynamic 
link library. 

Format 

OLD 'filename' 

Remarks 

If 'filename' is not found in the current directory, the linker looks in 
the list of directories in the user's PATH environment variable. 

Exported names in this module matching exported names in the OLD 
module will be assigned ordinal values from the OLD module unless: 

• The name in the OLD module does not have an assigned ordinal. 

• An ordinal is explicitly assigned to the name in this dynamic link 
library. 

The OLD statement is useful for preserving export ordinals across 
successive versions of a dynamic link module. 

Example 

OLD 'doscalls.dll' 
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PROTMODE 

Sets a program module to run in the OS/2 envi 
ronment 



Purpose 

Directs the linker to set tlie OS/2-bit in tiie OS/2 executable file 
header. PROTMODE specifies that the program module runs In the 
OS/2 environment only. 

Format 

PROTMODE 

Remarks 

PROTMODE designates that the executable file is not to be operated 
In the DOS mode; that is, it will not be "bound" using the BIND utility. 
If your program is never to run in the DOS mode, use PROTMODE to 
eliminate the floating-point fix ups and entry table entries for internal- 
reference fix ups from the executable file. Eliminating them removes 
wasted space in the file of OS/2-environment-only programs. 

Example 

PROTMODE 
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SEGMENTS 

Defines the attributes off code and data segments 



Purpose 

Defines the attributes of code and data segments on a per segment 
basis. Tlie specified parameters override tlie CODE and DATA state- 
ments' defaults. Tiie SEGMENT statement must precede all other 
definitions, and you can specify any number of segment definitions 
after the SEGMENT statement. You must type each segment defi- 
nition on a separate line. 

Format 

SEGMENTS segmentname class load readonly executeonly iopi 
shared 

Remarics 

segmentname Defines the code or data segment whose attributes are 
being specified. Enclose segmentname in single quotes 
if It is equal to a definition statement keyword such as 

'DATA' or 'CODE'. 

class (optional) A keyword which specifies the class of the 
segment, such as 

CLASS 'classname'. 

If no 'classname' is given, the linker assumes class 
'CODE'. Any segment whose classname ends in 'CODE' 
(case ignored) is recognized as a code segment by the 
linker: if a segment is defined without a CLASS option, it 
becomes type code. 

load (optional) A keyword which specifies when a segment is 

to be loaded. Specify one of the following: 

PRELOAD Load the segment immediately. 

LOADONCALL (default) Load the segment on demand. 

readonly (optional) A keyword which specifies the access rights to 
data segments. 
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SEGMENTS 

Defines the attributes of code and data segments 

READONLY Sets access rights to read only. 

READWRITE (default) Sets access rights to read or write. 

executeonly (optional) A l<eyword which specifies the access rights to 
code segments. 

EXECUTEONLY Sets access rights to execute only. 

EXECUTEREAD. (default) Sets access rights to execute 
or read. 

(optional) The keyword iopi specifies whether or not seg- 
ments have I/O privilege. This option applies to both 
code and data segments. 

lOPL Segments have I/O privilege. 

NOIOPL (default) Segments do not have I/O privilege. 

(optional) Specifies whether or not a unique copy of the 
READWRITE data segments should be loaded for each 
process using a dynamic link module. You can specify 
the following values: 

SHARED A single copy of each data segment Is loaded. 
The copy is shared by all processes using the 
dynamic link module. 

NONSHARED A unique copy of each READWRITE data 
segment is loaded for each process using the 
dynamic link module. 

Default: NONSHARED for program modules and 
SHARED for dynamic link libraries. 

Example 

SEGMENTS 

CSEG LOADONCALL 
CSEG2 EXECUTEREAD 
DSEGl READONLY 
DSEG2 SHARED 
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iopI 



shared 



STAGKSIZE 
Defines stack size in bytes 



Purpose 

Defines the number of bytes an application needs for its staclc. Tlie 
value specified for STACKSIZE overrides tlie size of any stack 
segment defined in the application. 

Format 

STACKSIZE bytes 
Remarks 

bytes An (integer) number which specifies the stack size. 

Example 

STACKSIZE 1024 
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STUB 

Appends DOS executable file to the OS/2 program 
module 



Purpose 

Appends the DOS executable file to the top of the OS/2 program 
module being created. The stub is called if the OS/2 program module 
is executed under DOS. For example, the stub could display a 
warning message and terminate. 

Format 

STUB 'filename' 

Remarks 

'filename' The name of the DOS executable file. 

If 'filename' is not found in the current directory, the liniter looks in 
the list of directories in the user's PATH environment variable. 

Example 

STUB 'astub.exe' 
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Glossary 



abort. Cancel, end, fail, prema- 
turely end, stop. 

abnormal termination. Unusual ces- 
sation of processing prior to 
planned termination. 

access. To obtain use of storage, a 
device, or a service. 

access mode. A technique that is 
used to obtain a specific logical 
record from, or to place a specific 
logical record into, a file assigned 
to a mass storage device. 

active session. Foreground 
session. 

addressability. (1) The ability of a 
process to access code or data. 
(2) Size of an address space. 

algorithm. (1) A finite set of well- 
defined rules for the solution of a 
problem in a finite number of steps. 
(2) Method of calculation. 

allocate. To assign or use for a 
specific purpose. For example, to 
eissign memory for a programs data 
segment. 

alphanumeric character. Consisting 
of letters, numbers, and other char- 
acters, such as punctuation marks 
and mathematical symbols. 

American National Standard Code 
for Information interchange (ASCII). 

The code developed by ANSI for 
information interchange among data 
processing systems, data communi- 



cation systems, and associated 
equipment. The ASCII character set 
consists of 7-bit control characters 
and symbolic characters. 

American National Standards 
Institute. An organization spon- 
sored by the Computer and Busi- 
ness Equipment Manufacturers 
Association for establishing volun- 
tary industry standards. 

ANSI. American National Standards 
Institute. 

API. (1) Application Program Inter- 
face. (2) The OS/2 function calls. 

application. A program or group of 
programs that apply to a particular 
business area, such as the Inven- 
tory Control or the Accounts Receiv- 
able application. 

application program. A program 
used to perform an application or 
part of an application. 

archive. (1) A copy of a data set 
that can be used if the original data 
is lost. (2) The storage of object 
files in a library. 

ARF. Automatic Response File used 
in linking. 

ArgPointer. The address of a set of 
argument strings. 

argument. Numbers, letters, or 
words that change the execution of 
a command. 
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ASCII. American National Standard 
Code for Information Interchange, 
normally to refer to a string of char- 
acters. 

ASCIIZ. American National 
Standard Code for Information Inter- 
change, normally to refer to a string 
of ASCII characters where the string 
is terminated with a byte of 0. 

ASM. Abbreviation for Assembler. 

assembler. A computer program 
that translates an assembly lan- 
guage source code file into a form 
that can be executed. 

asynchronous. (1) Without regular 
time relationship. (2) Unexpected 
or unpredictable with respect to the 
execution of a program's 
instructions. 

attribute. A characteristic or prop- 
erty of one or more entities, for 
example, the attribute for a dis- 
played field could be blinking. 

automatic mode. A method of oper- 
ation that, under specific conditions, 
does not require human inter- 
vention. 

auxiliary. A process or device not 
under direct control of the proc- 
essing unit. 

bimodal. Pertaining to both the DOS 
mode and the OS/2 mode. 

binary. (1) Pertaining to a system 
of numbers to the base two; the 
binary digits are 0 and 1. 
(2) Involving a choice of two condi- 
tions. 



binary string. A sequence of con- 
secutive binary digits. 

bit. Either of the binary digits 0 or 1 
used in computers to store informa- 
tion. 

block. (1) To wait, usually for an 
I/O event to complete or for a 
resource to become available. 
(2) A storage area used to hold 
information. 

boot. Initial program load after 
reset. 

BPB. BIOS Parameter Block 

buffer. (1) A temporary storage 
unit, especially one that accepts 
information at one rate and delivers 
it at another rate. (2) An area of 
storage, temporarily reserved for 
performing input or output, from 
which data is read, or into which 
data is written. 

buffer address. A numeric value 
denoting a unique memory location 
for a buffer. 

byte. The amount of storage 
required to represent one character; 
a byte is 8 bits. 

bytes per sector. The term used to 

Identify the number of bytes that can 
be stored on a sector of a 
disk/diskette (i.e., 512). 

CALL. The action of bringing a 
computer program, a routine, or a 
subroutine into effect, usually by 
specifying the entry conditions and 
an entry point. 

CF. Carry flag. 
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character. A letter, digit, or other 
symbol. 

character display. A display that 
uses a character generator to 
display predefined character boxes 
of images (characters) on the 
screen. This kind of display cannot 
address the screen any less than 
one character box at a time. 

character key. A keyboard key that 
allows the user to enter the char- 
acter shown on the key. 

character set. A group of charac- 
ters used for a specific reason; for 
example, the set of characters a 
printer can print or a keyboard can 
support. 

character string. A sequence of 

consecutive characters. 

character variable. The name of a 
character data item whose value 
may be assigned or changed while 
the program is running. 

child. (1) Pertaining to a secured 
resource, either a file or library, 
that uses the parent resources. A 
child resource can have only one 
parent resource. (2) A process 
created by a parent process that 
shares resources of parent process. 

child process. (1) A dependent 
process; contrast with parent 
process. (2) A process that is 
created by another process. 

CLI. Assembly language instruction 
to disable processor interrupts. The 
effect is to prevent hardware inter- 
rupts from being recognized by the 



processor until an STI instruction is 
issued. 

click. Press the mouse button (or 
press the mouse button twice in 
rapid succession). 

client process. A process that uses 
some service or dynamic link 
library. A process is a client of the 
service or library. 

close. (1) To end an activity and 
remove it from the display. (2) To 
release a device. 

code. (1) Instructions for the com- 
puter. (2) To write instructions for 
the computer; to program. (3) A 
representation of a condition, such 
as an error code. 

code page. The character 
encoding, for keyboard input and 
display and spooled printer output. 

code point. A single character or 
shape defined in the code page and 
presented on the display or printer. 

code segment. See segment 

COM. (1) Represents one of the 
serial communications ports sup- 
ported by OS/2 (COM1. COM2, 
COM3). (2) Communication. 

command. A request to perform an 
operation or run a program. When 
parameters, arguments, flags, or 
other operands are associated with 
a command, the resulting character 
string is a single command. 

command processor. (1) A 

program executed to perform an 
operation specified by a command. 
(2) A system or user task that proc- 
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esses a set of commands from a 
queue. 

compile. (1) To translate a 
program written in a high-level pro- 
gramming language into a machine 
language program. (2) The com- 
puter actions required to transform 
a source file into an executable 
object file. 

condition. An expression in a 
program or procedure that can be 
evaluated to a value of either true 
or false when the program or proce- 
dure is running. 

configuration. The group of 
machines, devices, and programs 
that mal<e up a computer system. 

constant. A data item with a value 
that does not change. 

context. The environment in which 
a program executes. 

contiguous. To be in actual contact 
with or touching along a boundary. 

coprocessor. A microprocessor on 
an expansion card or the system 
board. 

CS. Code Segment. 

current. Active. 

cursor. (1) A movable symbol 
(such as an underline) on a display, 
used to indicate to the user where 
the next typed character will be 
placed or where the next action will 
be directed. (2) A marker that indi- 
cates the current data access 
location within a file. 



customize. To describe (to the 
system) the devices, programs, 
users, and user defaults for a partic- 
ular data processing system. 

cylinder. All fixed-disk or diskette 
tracks that can be read or written 
without moving the disk drive or 
diskette drive read/write mech- 
anism. 

DASD. Direct Access Storage 
Device. 

data area. A storage area used by 
a program to hold information. 

DB. Define byte. A MASM 
pseudo-op to declare a byte of 

memory. 

DBCS. Double Byte Character Set 

DD. Define Double Word. A MASM 
pseudo-op to declare a double word 
of memory. 

dead key. Inactive key. 

deallocate. To release a resource 
that is assigned to a specific task. 

default value. A value stored in the 
system that is used when no other 
value is specified. 

deinstall. To remove. Used as a 
device driver command. 

delete. A function that enables data 
held in storage to be removed. 

delimiter. (1) A flag that separates 
and organizes items of data. Syn- 
onymous with punctuation symbol, 
separator. (2) A string of one or 
more characters used to separate 
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or organize elements of computer 
programs or data, for example, 
parenthesis, blank character, arith- 
metic operator, if, "BEGIN". (3) A 
character that groups or separates 
words or values in a line of Input. 

deregister. To remove. Used as a 
device monitor command. 

destination drive. The target drive 
in an operation involving two or 
more logical drives. 

DevHIp. Refers to the OS/2 services 
available in writing device drivers. 

device. An electrical or electronic 
machine that is designed for a spe- 
cific purpose and that attaches to a 
computer, for example, a printer, 
plotter, or disk drive. 

device attributes. Characteristics of 
a device, described in the device 
header of a device driver. 

device BPB. Data structure used to 
describe DASD devices. 

device driver. A program that oper- 
ates a specific device, such as a 
printer, disk drive, or display. 

device liandie. Device identifier. 

device name. A name reserved by 
the system or a device driver that 
refers to a specific device. 

device type. The general name for 
a kind of device. 

digit. Any of the numerals from 0 
through 9. 



directory. A type of file containing 
the names and controlling informa- 
tion for other files or other directo- 
ries. 

disabie. (1) To make nonfunctional. 
(2) The state of a processing unit 
that prevents the occurrence of 
certain types of interruptions. (3) A 
state in which a transmission 
control unit or audio response unit 
can not accept incoming calls. 

disk. A flat circular plate with a 
surface layer on which data can be 
stored by magnetic recording. 

diskette. A thin, flexible magnetic 
plate that is permanently sealed in a 
protective cover. It can be used to 
store information copies from the 
disk or another diskette. 

disicette drive. The mechanism 
used to read and write information 
on diskettes. 

dispatcli. To allocate time on a 
processor to jobs or tasks that are 
ready for execution. 

dispiay. (1) In word processing, a 
device for visual presentation of 
information on any temporary 
character-imaging device. (2) A 
visual presentation of data. (3) To 
present data visually. 

dispiay device. An output unit that 
gives a visual representation of 
data. 

dispiay screen. The part of the 
display device that displays infor- 
mation visually. 

DIM A. Direct Memory Access 
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DOS. (1) IBM Personal Computer 
Disk Operating System. (2) The 
DOS mode of OS/2. 

double-byte character. A single 
symbol requiring two bytes to code; 
for example, Chinese characters. 

dump. (1) To copy the contents of 
all or part of storage, usually to an 
output device. (2) Data that has 
been dumped. 

dump diskette. A diskette that con- 
tains a dump or is prepared to 
receive a dump. 

DW. Define Word. A MASM 
pseudo-op to declare a word of 
memory. 

dynamic priority variation. The 

changes in a thread's priority based 
on the state of the system and the 
state of thread relative to the 
system. 

EBCDIC. Extended Binary-Coded 
Decimal Interchange Code. 

EBCDIC character. Any one of the 

symbols included In the 8-bit 
EBCDIC set. 

enable. (1) To make functional. 
(2) The state of a processing unit 
that allows the occurrence of 
certain types of interruptions. 
^3^ The state in which a trans- 
mission unit can accept Incoming 
calls on a line. 

environment. The settings for vari- 
ables and paths set associated with 
each process. 

execute/execution. Do, start, or 
run. 



exit value. A numeric value that a 
command returns to indicate 
whether it completed successfully. 
Some commands return exit values 
that give other information, such as 
whether a file exists. 

expression. A representation of a 

value. For example, variables and 
constants appearing alone or in 
combination with operators. 

FAT. File Allocation Table. 

FCB. (1) Function control block. 

(2) File control block. (3) Forms 
control buffer. 

field. (1) An area in a record or 
panel used to contain a particular 
category of data. (2) The smallest 
component of a record that can be 
referred to by a name. 

FIFO. (1) FIrst-in-flrst-out. (2) A 
type of queue where the oldest ele- 
ments in the queue are removed 
before any newer elements. 

(3) Order of transferred data 
packets. 

file. A collection of related data that 
is stored and retrieved by an 
assigned name. 

file handle. File identifier. 

file pointer. An internal name that 
is a pointer to a structure containing 
information about a file. 

file specification. The name and 
location of a file. A file specification 
consists of a drive specifier, a 
pathname, and a filename. 
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file system. The collection of files 
and file management structures on 
a physical or logical mass storage 
device. 



function. (1) A specific purpose of 
an entity, or its characteristic 
action. (2) A synonym for proce- 
dure. 



fiiename. (1) The name used by a 
program to identify a file. (2) The 
portion of the identifying name that 
precedes the extension. 

fllespec. See File specification. 

filter. A command that reads 
standard input data, modifies the 
data, and sends it to standard 
output. 

fir8t-ln-first-out(FIFO). (1) A type of 
queue where the oldest elements In 
the queue are removed before any 
newer elements. (2) Order of trans- 
ferred data packets. 

fixed disk. A flat, circular, 
nonremovable plate with a surface 
layer on which data can be stored 
by magnetic recording. 

flag. (1) A modifier that defines the 

action of a command. (2) The 
action or return from a command. 

floppy disk. Deprecated term for 
diskette. 

flush. Delete, erase, or remove. 

foreground session. The session 
currently interacting with the user. 

format. (1) A defined arrangement 
of such things as characters, fields, 
and lines, usually used for displays, 
printouts, or files. (2) The pattern 
which determines how data is 
recorded. 



graphic character. (1) A character, 
other than a control character, that 
is normally represented by a 
graphic. (2) A character that can 
be displayed or printed. 

half-byte. Either the first or last four 
consecutive bits of a byte. A 
hexadecimal character represents a 
half-byte. 

hard disk. Fixed disk. 

hard error. (1) Error caused by the 
state of the hardware (e.g., printer 
off-line). (2) An unrecoverable 
error. 

hertz (Hz). A unit of frequency 
equal to one cycle per second. 

hexadecimal code. A code based 
on the radix 16, in which the digits 0 
through 9 and the letters A through 
F represent the code. 

hot key. A key recognized by the 
system as a request for a particular 
service or action. OS/2 has two hot 
keys: Ctrl + Esc to return to the 
Program Selector and Alt+ Esc to 
switch between active sessions. 

hung. Halted or stopped. 

Hz. Abbreviation for hertz. 

init. Initialization, usually refers to 
an initialization routine. 

initialize. To set counters, switches, 
addresses, or contents of storage to 
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zero or other starting values at the 
beginning of, or at prescribed 
points, in the operation of a conn- 
puter routine. 

input. (1) Pertaining to a device 
process, or channel involved in an 
input process, or to the data or 
states involved in an input process. 
(2) Data to be processed. (3) Syn- 
onymous with input data, input 
process. 

input device. Physical devices used 
to provide data to a computer. 

interactive. (1) Permitting contin- 
uous dialog between the user and 
the operating system. (2) Per- 
taining to an application in which 
each entry calls forth a response 
from a system or a program. 

interactive processing. A proc- 
essing method in which each 
system user action causes response 
from the program or the system. 

interface. A shared boundary 
between two or more entities. An 
interface might be a hardware com- 
ponent to link two devices together 
or it might be a portion of storage or 
registers accessed by two or more 
computer programs. 

interrupt-time. A generic term that 
refers to executing code as a result 

wi cli I iiiLOiiupii Liio iiiiocivi v/i 

cutlon does not belong to a process. 
i/0. Input/output. 

IPC. Interprocess Communications 
via semaphores, pipes, queues, etc. 



IPL. (1) Initial program load; the 
first time the operating system is 
loaded into memory and initialized. 
(2) To reload and initialize the oper- 
ating system via a power off/on or 
by pressing Ctrl + Alt+ Del. 

invoice. To activate a procedure at 
one of its entry points. 

KB. Kilobyte. 

kbd. keyboard. 

KGB. (1) Keyboard Control Block. 
(2) A data area containing variables 
pertaining to a given logical key- 
board, created by the KbdOpen API. 

icili. To end or suppress a process. 

Kiiobyte. 1024 bytes. 

iabei. (1) The name in the disk or 
diskette directory that identifies a 
file. (2) The field of an instruction 
that assigns a symbolic name to the 
location at which the instruction 
begins. 

LIB. (1) An abbreviation for library. 
(2) Used as an extension on library 
files. (3) The Librarian utility which 
creates and manages Object 
Libraries. 

library. A collection of functions, 
calls, subroutines, or other data. 

linefeed. An ASCII character that 
causes an output device to move 
forward one line. 

load. (1) To move data or pro- 
grams into storage. (2) To place a 
diskette into a diskette drive. (3) To 
insert paper into a printer. 
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logical device. Redirected disk, file, 
printer, or other specific device. 

memory. Storage on electronic 
cl^ips. Examples of memory are 
random access memory, read only 
memory, or registers. 

memory compaction. Relocating 
allocated storage segments into 
contiguous locations in order to 
place all free storage in one large 
block. 

menu. A displayed list of items 
from which a user can make a 
selection. 

message. A response from the 
system to inform the user of a con- 
dition which may affect further proc- 
essing of a program. 

module. A discrete programming 
unit that usually performs a specific 
task or set of tasks. 

monitor. (1) A routine which exam- 
ines input to a character device 
driver and can delete, modify, or 
expand the character before 
passing it back to the device driver. 
(2) A routine which filters the 
Input/output stream. 

muiti. Two or more. 

multiprogramming. (1) A mode of 
operation that provides for the inter- 
leaved execution of two or more 
computer programs by a single 
processor. (2) The processing of 
two or more programs at the same 
time. 

multitasicing. The concurrent exe- 
cution of two or more tasks by a 
computer. 



nest. To incorporate a structure or 
structures of some kind into a struc- 
ture of the same kind. For example, 
to nest one loop (the nested loop) 
within another loop (the nesting 
loop); to nest one subroutine (the 
nested subroutine) within another 
subroutine (nesting subroutine.) 

NPX. Numeric Coprocessor 

NUL. Null character 

null. Having no value, containing 
nothing. 

nuii character (NUL). The character 
hex 00, used to represent the 
absence of a printed or displayed 
character. 

numeric. Pertaining to any of the 
digits 0 through 9. 

OBJ. A file name extension that 
identifies a relocatable object file. 

object code. Machine-executable 
instruction, usually generated by a 
compiler from source code written 
in a higher level language. Con- 
sists of directly executable machine 
code. For programs that must be 
linked, object code consists of relo- 
catable machine code. 

object file. A program unit that is 
the output of an assembler or a 
compiler and is suitable for input to 
the linker. 

object module. Synonym for object 

file. 

octal. A base eight numbering 
system. 
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offset. The number of measuring 
units from an arbitrary starting point 
in a record, area, control b\ocK or a 
segment to some other point. 

online. (1) Pertaining to a user's 
ability to Interact with a computer. 
(2) Pertaining to the operation of a 
functional unit that is under the con- 
tinual control of a computer. 

open. To make a file or device 
available to a program for proc- 
essing. 

operand. (1) An entity to which an 
operation is applied. (2) That which 
is operated upon. An operand Is 
usually identified by the address 
part of an instruction. (3) Informa- 
tion entered with a command name 
to define the data on which a 
command processor operates and 
to control the execution of the 
command processor. (4) An 
expression to whose value an oper- 
ator Is applied. 

operating system. Software that 
controls the running of programs; in 
addition, an operating system may 
provide services such a resource 
allocation, scheduling, input/output 
control, and data management. 

option. A specification In a state- 
ment that can be used to Influence 
the execution of the statement. 

output. (1) Synonym for output 
data; output process. (2) The result 
of processing. 

output device. The physical device 
used by a computer to present data 
to a user. 



output file. A file that is opened by 
a program so that the program can 
write to that file. 

parameter. Information supplied by 
the programmer or user to a 
command, or function. An attribute, 
value, or variable. 

parent. The owning or creating 
process, as opposed to a child 
process. 

parent directory. The directory one 
level above the current directory. 

parm. Abbreviation for parameter. 

PgmPointer. The address of an 
ASCIIZ string of the drive, directory 
path and filename of the program to 
be executed. 

physicai device. Device. 

pipe. To direct the data so that the 
output from one process becomes 
the Input to another process. 

pixel. Picture element. 

pop. Retrieving Information from a 
stack. 

preempt. To take control away 
from, such as, to Interrupt the exe- 
cution of a process to allow another 
process to execute. 

print queue. A file containing a list 
of the names of files waiting to be 
printed. 

print spooler. The program which 
manages the print queue. 
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priority. A rank assigned to a task 
that determines Its precedence in 
receiving system resources. 

procedure. (1) The course of action 
taken for the solution of a problem. 
(2) The description of the course of 
action taken for the solution of a 
problem. 

process. A collection of system 
resources including one or more 
threads. 

process ID. A unique number 
assigned to a process. 

prompt. A displayed request for 
information or user action. 

protect mode. A mode of 80286 

memory addressing in which virtual 
addresses are mapped to physical 
addresses by on-chip circuitry. 

jBseudo. Artificial, simulated. 

Puil. To remove from. 

push. Placing information on a 
stack (to put on or In). 

queue. A line or list formed by 
Items waiting to be processed. 

RAM semaphore. A simple, effi- 
cient form of semaphore used to 
serialize different threads of a 
single process. 

random access. An access mode in 
which records can be read from, 
written to, or removed from a file in 
any order. 

RAS. Reliability, Availability, and 
Serviceability. 



redirection. The reassignment of 
the standard input and standard 
output devices. 

refresh. The process of repeatedly 
producing a display image on a 
display space so that the image 
remains visible. 

RET. Return. 

return code. A code returned by a 
function, which the caller may use 
to influence the execution of suc- 
ceeding instructions. 

reverse video mode. A form of 
highlighting a character, field, or 
cursor by reversing the color of the 
character, field, or cursor with its 
background; for example, changing 
a red character on a black back- 
ground to a black character on a red 
background. 

routine. Part of a program, or a 

sequence of instructions called by a 
program, that may have some 
general or frequent use. 

run. To cause a program, utility, or 
other machine function to be per- 
formed. 

run time. The elapsed time taken 
for the execution of a computer 
program. Synonymous with run 
duration. 

sector. An area on a disk track or a 
diskette track reserved to record 
information 

segment. A contiguous area of 
storage. 
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semaphore. A signal mechanism 
used to control access to system 
resources. 

separator. A character used to sep- 
arate parts of a command or file. 

sequential access. An access 
method in which records are read 
from, written to, or removed from a 
file based on the physical order of 
the records. 

session. A routing mechanism for 
user interaction via the console. 

siiared data segment. A data area 
created in memory that can be 
shared by programs. 

siiared memory. An OS/2 feature 
that allows system memory to be 
shared among processes. 

source module. The source state- 
ments or codes that constitute the 
input to the compiler or assembler 
for translation. 

source program. A set of 

instructions written in a program- 
ming language, that must be trans- 
lated to machine language complied 
before the program can be run. 

spawn. Create, develop, generate. 

stacic. An area in storage that 
stores temporary register informa- 
tion, parameters, and return 
addresses of subroutines. 

stacic pointer. A register that con- 
tains the current location of the top 
of the stack. 



standalone. Pertaining to oper- 
ations that are independent of 
another device, program, or system. 

standard input. The primary source 
of data going into a command. 
Standard input comes from the key- 
board unless redirection or piping is 
used, in which case standard input 
can be from a file or the output from 
another command. 

standard output. The primary desti- 
nation of data coming from a 
command. Standard output goes to 
the display unless redirection or 
piping Is used, in which case 
standard output can be a file or 
another command. 

storage. (1) The location of saved 
information. (2) In contrast to 
memory, the saving of information 
on physical devices such as disk or 
tape. 

string. A linear sequence of entities 
such as characters or physical ele- 
ments. Examples of strings are 
alphabetic string, binary element 
string, bit string, character string, 
search string, and symbol string. 

suballocation. The allocation of a 
part of one extent for occupancy by 
elements of a component different 
from the one occupying the 
remainder of the extent. 

sulMllrectory. A directory contained 
within another directory In the file 
system hierarchy. 

subroutine. (1) A sequence of 
statements that may be used in one 
or more computer programs and at 
one or more points in a computer 
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program. (2) A routine that can be 
part of another routine. 

swap file. A file that contains seg- 
ments of a program or data tempo- 
rarily moved out of main storage. 

synchronous. Pertaining to two or 
more processes that depend upon 
the occurrences of specific events 
such as common timing signals. 

system. The computer and its asso- 
ciated devices and programs. 

task-time. A generic term that 
refers to executing code as a thread 
within a process. 

terminate. Conclude, end, finish, 
stop. 

thread. A unit of execution within a 
process. 



toggle. Change or switch. 

transposition. To change the order 
as to reverse the order. 

typeamatic Icey. A l<ey that repeats 
Its function when held down. 

vaiid. Correct. 

variabie. A parameter with different 
values at any one time. The values 
are usually restricted to data type. 

wiidcard character. Global filename 
characters. 

write protection. Restriction of 
writing into a data set, file, or 
storage area by a user or program 
not authorized to do so. 
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DevHIp ABIOSCommonEntry 8-12 

DevHIp character queue 
structure 7-12 

DevHIp EOl 8-24 

DevHIp FreeLIDEntry 8-26 

DevHIp function codes 8-1 

DevHIp GetLIDEntry 8-31 

DevHIp modes 8-3 

DevHIp services 8-1 

DevHIp TickCount 8-84 

DevHIp UnPhysToVIrt 8-87 

DevHIp VerifyAccess 8-90 

DevHIp, AllocGDTSelector 8-14 

DevHIp, AllocPhys 8-16 

DevHIp, AllocReqPacket 8-17 

DevHIp, Block 8-19 

DevHIp, DeRegister 8-22 

DevHIp, DevDone 8-23 

DevHIp, FreePhys 8-27 

DevHIp, FreeReqPacket 8-28 

DevHIp, GetDOSVar 8-29 

DevHIp, Lock 8-33 

DevHIp, MonFlush 8-35 

DevHIp, MonitorCreate 8-36 
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DevHIp, MonWrite 8-39 
DevHIp. PhysToGDTSelector 8-41 
DevHIp, PhysToUVirt 8-43 
DevHIp, PhysToVirt 8-45 
DevHIp, ProtToReal 8-49 
DevHIp, PullParticular 8-51 
DevHIp, PullReqPacket 8-52 
DevHIp, PushReqPacket 8-53 
DevHIp, QueueFlush 8-54 
DevHIp, Queuelnit 8-55 
DevHIp, QueueRead 8-56 
DevHIp, QueueWrite 8-57 
DevHIp, RealToProt 8-58 
DevHIp, Register 8-60 
DevHIp, ResetTlmer 8-62 
DevHIp, ROMCritSectlon 8-63 
DevHIp, Run 8-65 
DevHIp, SchedClockAddr 8-66 
DevHIp, SemClear 8-68 
DevHIp, SemHandle 8-70 
DevHIp, SemRequest 8-73 
DevHIp, SendEvent 8-75 
DevHIp, SetlRQ 8-77 
DevHIp, SetROMVector 8-78 
DevHIp, SetTimer 8-80 
DevHIp, SortReqPacket 8-82 
DevHIp, TCYIeld 8-83 
DevHIp, Unlock 8-86 
DevHIp, UnSetlRQ 8-89 
DevHIp, VIrtToPhys 8-92 
DevHIp, Yield 8-93 
device attribute 7-22, 7-23 
DEVICE CLOSE 7-58 
device driver 

attribute 7-23 

command codes 7-42 

header 7-21 

request packet 7-37 
device driver architecture 

bi modal device driver 
operation 7-8 

components of a device 
driver 7-5 

types of device drivers 7-2 



device driver commands 
BUILD BPB 7-50 
FLUSH 7-57 
GENERIC lOCtI 7-60 
INIT 7-43 

LOGICAL DRIVE 7-62 
MEDIA CHECK 7-47 
NONDESTRUCTIVE READ NO 

WAIT 7-55 
OPEN or CLOSE 7-58 
READ 7-53 

REMOVABLE MEDIA 7-59 

RESET MEDIA 7-61 

STATUS 7-56 

WRITE 7-53 
device driver contexts 7-7 
device driver data segment, 

Advanced BIOS 7-34 
device driver DEINSTALL 7-63 
device driver examples 7-68 
device driver function calls 

DosBeep 7-27 

DosCaseMap 7-27 

DosChgFilePtr 7-27 

DosClose 7-27 

DosDelete 7-27 

DosDevConfig 7-27 

DosDevlOCtI 7-27 

DosFindClose 7-27 

DosFindFirst 7-27 

DosFindNext 7-27 

DosGetCtrylnfo 7-27 

DosGetDBCSEv 7-27 

DosGetEnv 7-27 

DosGetMessage 7-27 

DosOpen 7-27 

DosPutMessage 7-27 

DosQCurDir 7-27 

DosQCurDisk 7-27 

DosQFilelnfo 7-27 

DosQFileMode 7-27 

DosRead 7-27 

DosWrite 7-27 
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device driver functions 
device driver GET FIXED 

DISK/LOGICAL UNIT MAP 7-66 
device driver header 7-21, 7-22 
device driver initialization 7-26 
device driver interrupt 

sliaring 7-13 
device driver notes/using Advanced 

BIOS 7-72 
device driver PARTITIONABLE 

FIXED DISKS 7-65 
device driver program model 7-21 
device driver, application 

access 7-3 
device driver, bimodal 

operations 7-1 
device driver, blocic 7-2 
device driver, character 7-2 
device driver, creating 7-26 
device driver, DOS mode 7-4 
device driver, DosDevlOCtI 7-3 
device driver, dual mode 7-1 
Device Driver, EGA.SYS 9-102 
device driver, interrupt handling 

rules 7-6 
device driver, interrupt sharing 

rules 7-14 
device driver, multiple block 

devices 7-2 
device driver, multiple character 

devices 7-2 
device driver, previous-level 7-29 
device driver, queueing 

requests 7-9 
device driver, software interrupt 

handler 7-6 
device driver, strategy routine 7-5 
device driver, timer handler 7-6 
device driver, types 7-2 
device drivers, OS/2 
commands, printer 

device 9-158 
creating 7-26 

device driver architecture 7-1 



device drivers, OS/2 (continued) 

device header 7-21 

diskette device driver 9-137 

fixed disk device driver 9-138 

printer device driver 9-154 

responses, printer device 9-158 

status word 7-40 
device field, next 7-22 
device header 7-21 
device header fields 

attribute 7-22 

header 7-22 

name/unit 7-25 

next device header 7-22 

strategy routine 7-24 
device helper services 8-1 

ABIOSCall 8-3 

ABIOSCommonEntry 8-3 

AllocGDTSelector 8-3 

AllocPhys 8-3 

AllocReqPacket 8-3 

Block 8-3 

character queue 
management 7-12 

DeRegister 8-3 

DevDone 8-3 

DevHIp interfaces 8-9 

EOl 8-3 

FreeLIDEntry 8-3 
FreePhys 8-3 
FreeReqPacket 8-3 
function codes 8-1 
GetDOSVar 8-3 
GetLIDEntry 8-3 
GrantPortAccess 8-3 
Lock 8-3 

memory management 7-10 
MonFlush 8-3 
MonitorCreate 8-3 
MonWrite 8-3 
PhysToGDTSelector 8-3 
PhysToVIrt 8-3 
PortUsage 8-3 
ProtToReal 8-3 
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device helper services (continued) 
PullReqPacl<et 8-3 
PushReqPacl<et 8-3 
QueueFlush 8-3 
Queuelnit 8-3 
QueueRead 8-3 
QueueWrite 8-3 
RealToProt 8-3 
Register 8-3 
ResetTlmer 8-3 
ROI\/ICritSeotion 8-3 
Run 8-3 

ScliedClockAddr 8-3 

semaphore management 7-1 1 

SemClear 8-3 

SemHandle 8-3 

Sem Request 8-3 

Send Event 8-3 

services and corresponding 

states 8-3 
SetlRQ 8-3 
SetROMVector 8-3 
SetTimer 8-3 
SortReqPacl<et 8-3 
TCYield 8-3 
Ticl<Count 8-3 
Unlocl< 8-3 
UnPhysToVirt 8-3 
UnSetlRQ 8-3 
VerifyAccess 8-3 
VirtToPhys 8-3 
Yield 8-3 
device names 6-3 
CLOCKS 6-3 
COI\41-COIVI3 6-3 
CON 6-3 
KBO$ 6-3 
LPT1 or PRN 6-3 
LPT2 6-3 
LPT3 6-3 
I^OUSE$ 6-3 
NUL 6-3 
POINTERS 6-3 
SCR 6-3 



device names (continued) 
SCREENS 6-3 

DEVICE OPEN 7-58 

device status report 9-128 

device type bit 7-23 

DEVICE = parameter string 

character device monitors 6-32 
device driver architecture 7-1 
device driver examples 7-68 
device driver header 7-22 
device driver program 

model 7-21 
device monitor services 6-32 
driver 7-38 

EXTDSKDD.SYS device 9-148 
replacing character device 7-28 

devices, Ill-behaved 7-15 

devices, well-behaved 7-15 

DGROUP A-8 

directory entries 

disabled state support 9-33 

disabling far call translations A-18 

disk 

diskette 

Diskette, Create Dump 10-2, 10-9 
displaying Information about the 

linking process A-14 
done bit 7-41 

DOS mode device driver 7-4 
DOS mode EGA 

considerations 6-26 
DOS mode exceptions 2-19 
DOS mode INT 33H mouse 

API 6-31 
DOS mode Mouse 9-66 
DOS Mode Mouse - 

Coordinates 9-57 
DOS Mode Mouse - Display Modes 

Supported 9-59 
DOS Mode Mouse - 

Handler/Router 9-57 
DOS Mode Mouse - lOCtI 

Calls 9-58 
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DOS Mode Mouse - Motion 9-58 
DOS mode Mouse - Overview 9-56 
DOS mode Mouse - Pointer 9-59 
DOS Mode Mouse API 9-61 
DOS mode sharing rule 7-15 
DOS mode Software Interrupt 

Support 7-31 
DOS mode, device driver 7-4 
DOS mode, interrupt sharing 7-15 
DosError 4-29 
DosRealiocSeg A-28 

services A-28 
DosSetVec 4-30 
dual mode device drivers 7-1 
Dump Facility 10-2, 10-5 
Dump, Create Diskette Utility 10-2, 

10-9 

dynamic link 2-4 
dynamic link calls, device 

driver 7-27 
Dynamic Link Conventions 2-3 
dynamic linking 4-26 
dynamic linking, run time 4-26 

E 

EGA considerations, DOS 

mode 6-26 
EGA.SYS Device Driver 9-102 
EOl 8-24 
eoi rule 7-17 
erase control sequences 
erase in display 9-130 
erase in line 9-130 
erase in display control 

sequence 9-130 
erase in line control 

sequence 9-130 
erasing control sequences 9-130 
error bit 7-40 
error codes 

error codes, status word 7-41 
error handling 
error codes 4-29 



error handling (continued) 
errors and exceptions 4-29 
errors, function requests 4-29 
function request errors 4-29 
handling machine 
exceptions 4-29 
hard error handling 4-29 
hard error override 4-29 
return codes, function 
requests 4-29 

errors and exceptions function calls 
DosSetVec 4-30 

events 

event mask 9-65 
mickeys/row and column 9-55 
row and column/mickeys 9-55 
time 9-55 

example 2-7, 2-8 

examples of device drivers 7-68 

EXE file information 4-28 

executable files A-10 
packing A-10 

EXPORTS statement A-55 

Extended DOS Partition 9-139 

extended partition 9-138 

extended screen and keyboard, 
using 

control sequence syntax 9-123 
cursor control sequences 9-125 
limitations/restrictions 9-123 

extended start-up record 9-139 

extended volume 9-139 

extension 

extensions, system 3-1 1 

F 

family API 2-11 

full function API 2-11 
far call translations, 

disabling A-18 
FAT (see File Allocation Table) 
field name 7-25 
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field, attribute 7-22 


function calls (continued) 


file 


DosFreeSeg 3-8 


file handles 


DosGetEnv 4-32 


file I/O 


DosGetHugeShlft 3-8 


file sectors 


DosGetMessage 4-30 


filename 


DosGetModHandle 4-29 


filename extension 


DosGetModName 4-29 


files A-6 


DosGetProcAddr 4-29 


fix-ups A-30 


DosGetSeg 3-8 


long A-30 


DosGetShrSeg 3-8 


near segment-relative A-30 


DosGetVersion 4-32 


near self-relative A-30 


DosGiveSeg 3-8, 4-17 


short A-30 


DosHoldSignal 4-25 


format bit 7-23 


DoslnsMessage 4-30 


Formatter Utility, Trace 10-7 


DosLoadModule 4-29 


FreeLIDEntry 8-26 


DosLockSeg 3-8 


FreePhys 8-27 


DosMem Avail 3-8 


FreeReqPacket 8-28 


DosMkDir 6-15 


full draw support 9-32 


DosMonClose 6-38 


function call 2-4 


DosMonOpen 6-38 


function call rules 2-3 


DosMonRead 6-38 


function call summary (MSP) 3-10 


DosMonReg 6-38 


system extensions 3-10 


Dos M on Write 6-38 


Function Calling Sequences 2-3 


Dos Move 6-15 


function calls 2-4, 2-6, 2-7, 2-8 


DosNewSize 6-15 


DosAllocHuge 3-8 


DosOpen 6-15 


DosAllocSeg 3-8, 4-17 


DosOpenQueue 4-15, 4-17 


DosAllocShrSeg 3-8 


DosPeekQueue 4-15 


DosBufReset 6-15 


DosPurgeQueue 4-15 


DosChDir 6-15 


DosPutMessage 4-30 


DosChgFilePtr 6-15 


DosQCurDir 6-15 


DosClose 6-15 


DosQCurDisk 6-15 


DosCloseQueue 4-15 


DosQFHandState 6-15 


DosCreateCSAIias 3-8 


DosQFilelnfo 6-15 


DosCreateQueue 4-15 


DosQFileMode 6-15 


DosDelete 6-15 


DosQFslnfo 6-15 


DosDelete. 6-15 


DosQHandType 6-15 


DosDupHandle 6-15 


DosQueryQueue 4-15 


DosFilsLocks 6-15 


DosQVerlfy 6-15 


DosFindClose 6-15 


DosRead 6-15 


DosFlndFirst 6-15 


DosReadAsync 6-15 


DosFindNext 6-15 


DosReadQueue 4-15 


DosFlagProcess 4-25 


DosReallocHuge 3-8 


DosFreeModule 4-29 


DosReallocSeg 3-8 
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function calls (continued) 

DosRmDIr 6-15 

DosSelectDisk 6-15 

DosSetFHandState 6-15 

DosSetFilelnfo 6-15 

DosSetFileMode 6-15 

DcsSetFslnfo 6-15 

DosSetMaxFH 6-15 

DosSetSession 5-4 

DosSetSigHandler 4-25 

DosSetVerIfy 6-15 

DosStartSession 5-4 

DosStopSession 5-4 

DosSubAlloc 3-10 

DosSubFree 3-10 

OosSubSet 3-10 

DosUnlockSeg 3-8 

Dos Write 6-15 

DosWrlteAsync 6-15 

DosWrlteQueue 4-15 
function calls, INT21 

G 

Generic lOCtI 7-30, 7-60 
Generic lOCtI, Category 8 9-147 
generic lOCtI, category 9 9-147 
get 

Get Device Parameters 9-147 
GET FIXED DISK/LOGICAL UNIT 

MAP 7-66 
GET LOGICAL DRIVE MAP 7-62 
GetDOSVar 8-29 
GetLIDEntry 8-31 
greater than 32Mb partitioned 
support 
BPB and get device 
parameters 9-147 
creating block devices 9-143 
deleting block devices 9-143 
extended DOS partition architec- 
ture 9-139 
installing block devices 9-141 



groups 

DGROUP A-8 

H 

handle 

hardware interrupt 

management 7-13 
hardware interrupt sharing 7-13 
hardware interrupts, 

DEINSTALL 7-64 
header, device driver 7-22 
HEAPSIZE statement A-57 
horizontal position 9-127 

I 

i/o privilege model 4-27 
I/O services 6-1 

ASCIIZ strings 6-1 

DosBuf Reset 6-15 

DosChDir 6-15 

DosChgFilePtr 6-15 

DosClose 6-15 

DosDelete 6-15 

DosDupHandle 6-15 

DosFileLocks 6-15 

DosFindClose 6-15 

DosFindFirst 6-15 

DosFindNext 6-15 

DosMkDir 6-15 

DosMove 6-15 

DosNewSIze 6-15 

DosOpen 6-15 

DosOCurDir 6-15 

DosQCurDlsk 6-15 

DosQFHandState 6-15 

DosQFilelnfo 6-15 

DosQFIIeMode 6-15 

DosQFslnfo 6-15 

DosQHandType 6-15 

DosQVerIfy 6-15 

Dos Read 6-15 

DosReadAsync 6-15 
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I/O services (continued) 

DosRmDir 6-15 

DosScanEnv 6-15 

DosSearchPath 6-15 

DosSelectOisk 6-15 

DosSetFHandState 6-15 

DosSetFilelnfo 6-15 

DosSetFileMode 6-15 

DosSetFslnfo 6-15 

DosSetMaxFH 6-15 

DosSetVerify 6-15 

DosWrite 6-15 

DosWriteAsync 6-15 

file I/O function call 
summary 6-15 

file I/O services 6-14 

filename specification 6-1 

general information 6-1 

I/O support for the DOS 
mode 7-4 

video I/O services 6-16 
IBM C Compiler interface, 
example 2-9 

refid = OS/2.compatiblllty con- 
siderations 2-10 
id = OS/2.0S/2 

refid = 0S/2.f unction calls 2-1 
ignoring default libraries A-17 
ill-behaved device rule 7-15 
ill-behaved devices 7-16 
IMPORTS statement A-58 
Incorrect offset warning A-27 
Information A-14 
INIT 7-43 
INIT Mode 7-7 
INPUT FLUSH 7-67 
INPUT STATUS 7-56 
installed flag and reset 

conditional off 9-81 

get button press 
information 9-69 

get button release 
Information 9-70 

get position and button 
status 9-68 



installed flag and reset (continued) 
hide pointer 9-67 
light pen emulation off 9-79 
light pen emulation on 9-78 
query save mouse state 9-84 
read mouse motion 

counters 9-76 
restore mouse driver state 9-85 
save mouse drive state 9-84 
set dbl speed threshold 9-81 
set graphic pointer block 9-74 
set mickey/pixel ratio 9-80 
set Min & Max horiz 

position 9-72 
set Min & Max Vert 

position 9-73 
set pointer position 9-69 
set text pointer 9-75 
set user-defined 

subroutine 9-77 
show pointer 9-66 
swap user-defined 
subroutine 9-82 
int return rule 7-17 
INT 33H 9-35, 9-56, 9-61, 9-65, 9-66, 
9-67, 9-68, 9-69, 9-70, 9-72, 9-73, 
9-74, 9-75, 9-76, 9-77, 9-78, 9-79. 
9-80, 9-81, 9-82, 9-84, 9-85 



INT 


33H- 


Function 


Code 


OH 


9-65 


INT 


33H - 


Function 


Code 


1H 


9-66 


INT 


33H- 


Function 


Code 


10H 


9-75 


INT 


33H- 


Function 


Code 


11H 


9-76 


INT 


33H- 


Function 


Code 


12H 


9-77 


INT 


33H- 


Function 


Code 


13H 


9-78 


INT 


33H- 


Function 


Code 


14H 


9-79 


INT 


33H- 


Function 


Code 


15H 


9-80 


INT 


33H- 


Function 


Code 


16H 


9-81 


INT 


33H- 


Function 


Code 


19H 


9-81 


INT 


33H- 


Function 


Code 


2H 


9-67 


INT 


33H- 


Function 


Code 


20H 


9-82 


INT 


33H - 


Function 


Code 


21H 


9-84 


INT 


33H- 


Function 


Code 


22H 


9-84 


INT 


33H- 


Function 


Code 


23H 


9-85 
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INT 33H - Function Code 3H 9-68 

INT 33H - Function Code 4H 9-69 

INT 33H - Function Code 5H 9-69 

INT 33H - Function Code 6H 9-70 

INT 33H - Function Code 7H 9-72 

INT 33H - Function Code 8H 9-73 

INT 33H - Function Code 9H 9-74 

INT 33H Mouse API 9-61 

interface 2-4, 2-6 

Interface Rules 2-3 

interprocess communication 
messages 4-9 
refid = OS/2. interprocess com- 
munications 4-9 
semaphores 4-9 
shared memory 4-9 
signals 4-9 

interrupt handier, device 
driver 7-6 

interrupt handling rules, device 
driver 7-6 

Interrupt Mode 7-7 

interrupt processing 7-13 

interrupt processing, 8259 
enabling 7-16 

Interrupt routine 7-8 

interrupt sharing 7-13 

interrupt sharing, device depend- 
ency 7-13 

interrupt sharing, DOS mode Inter- 
rupt handler 7-15 

interrupt sharing, getting an 
IRQ 7-15 

Interrupt sharing. Ill-behaved 
device 7-15 

interrupt sharing, processing inter- 
rupts 7-16 

interrupt sharing, restrictions 7-14 

interrupt sharing, rules 7-14 

Interrupt Sharing, Serial 
Mouse 9-35 

interrupt sharing, support of DOS 
mode i/0 7-16 



interrupt sharing, well-behaved 
device 7-15 

interrupt sharing, with BIOS Inter- 
rupt handlers 7-15 

interrupt sharing, 8259 
enabling 7-16 

Interrupt 33 9-61 

Interrupt-time 7-7 

interrupts, OS/2 

intra-segment far calls A-18 

lOCtI 9-52 

lOCtI READ 7-53 

lOCtI WRITE 7-53 



IOMR_ 




9-53 


IOMR_ 


GK 


9-53 


IOMR_ 


GM 


9-53 


IOMR_ 


'gs 


9-53 


IOMR_ 


MC 


9-53 


IOMR_ 


NB 


9-53 


IOMR_ 


OS 


9-53 


IOMR_ 


RD 


9-53 


lOMW. 


_DP 


9-53 


lOMW. 


_EM 


9-53 


lOMW. 


_GP 


9-53 


lOMW. 


_RP 


9-53 


lOMW. 


_SK 


9-53 


lOMW. 


_SP 


9-53 


lOMW. 


_SS 


9-53 



IPC function calls 

DosCioseOueue 4-23 
DosCloseSem 4-23 
DosCreateQueue 4-23 
DosCreateSem 4-23 
DosMai<ePipe 4-23 
DosMuxSemWait 4-23 
DosOpenQueue 4-23 
DosOpenSem 4-23 
DosPeel<Queue 4-23 
DosPurgeQueue 4-23 
DosQueryQueue 4-23 
DosReadQueue 4-23 
DosResumeThread 4-23 
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IPC function calls (continued) 

DosSemClear 4-23 

DosSemRequest 4-23 

DosSemSet 4-23 

DosSemSetWait 4-23 

DosSemWait 4-23 

DosSuspendThread 4-23 

DosWrlteQueue 4-23 
IPC functions 

communicating witli a pipe 4-12 

communicating with a 
queue 4-13 

communication via 
messages 4-10 

communication via signals 4-10 

comparing pipes and 
queues 4-14 

comparing pipes with files 4-12 

comparing pipes with flags 4-12 
irq enforcement rule 7-15 
irq mask rule 7-16 
Irq ownership rule 7-16 

K 

KBD 9-133 

KbdStringIn 9-133 

Kernel Mode 7-7 

keyboard considerations 11-5 

keyboard device driver 9-89 

keyboard I/O services 

KbdCharIn 6-28 

KbdClose 6-28 

KbdDeRegister 6-28 

KbdFlushBuffer 6-28 

KbdFreeFocus 6-28 

KbdGetFocus 6-28 

KbdGetStatus 6-28 

KbdOpen 6-28 

KbdPeek 6-28 

KbdRegister 6-28 

KbdSetCustXt 6-28 

KbdSetFgnd 6-28 

KbdSetStatus 6-28 



keyboard I/O services (continued) 

KbdStringIn 6-28 

KbdSynch 6-28 

KbdXIate 6-28 

keyboard I/O function call 
summary 6-28 
keyboard reassignment 9-133 
keyboard run time operation 9-92 
keyboard, country support 11-3 
keys, reassign 9-133 
keystroke monitors 9-93 

L 

length of request packet field 7-38 
LIBRARY statement A-60 
line numbers A-15 

copying to the map file A-15 
LINK command options A-2 
LINK files, specifying A-32 
LINK fix-ups A-30 
LINK options A-2 

/CODEVIEW A-6 

/CPARMAXALLOC A-7 

/DOSSEG A-8 

/DSALLOCATE A-9 

/EXEPACK A-10 

/FARCALLTRANSLATION A-11 

/HELP A-12 

/HIGH A-13 

/INFORMATION A-14 

/LINENUMBERS A-15 

/MAP A-16 

/NODEFAULTLIBSEARCH A-17 
/NOFARCALLTRANSLATION A-18 
/NOGROUPASSOCIATION A-19 
/NOIGNORECASE A-20 
/NOPACKCODE A-21 
/OVERLAYINTERRUPT A-22 
/PACKCODE A-23 
/PAUSE A-24 
/SEGMENTS A-25 
/STACK A-26 
/WARNFIXUP A-27 
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LINK options (continued) 

abbreviations A-2 

ALIGNMENT 

ordering segments A-8 
linl<age field, request header 7-42 
linker options A-2 
linker utility, See link A-2 
Lock 8-33 

logical block device 9-139 
Logical IDs, DEINSTALL 7-64 
lowercase, preserving A-20 

M 

managing queues 

DosCloseQueue 4-16 

DosCreateQueue 4-16 

DosOpenQueue 4-16 

DosPeekQueue 4-16 

DosPurgeQueue 4-16 

DosQueryQueue 4-16 

DosReadQueue 4-16 

DosWrlteQueue 4-16 

process ID (PID) 4-17 

shared memory 4-17 

shared memory handle 4-17 
map A-16 

public symbol A-16 
map file A-32 
MEDIA CHECK 7-47 
memory 

memory addressability 7-10 
memory management 7-10 

function call summary 3-9 

memory management 
interface 3-8 

memory suballocation 3-9 

MSP summary 3-10 

protection features of the ring 
structure 3-1 

ring structure, protection fea- 
tures of 3-1 

segmentation hardware, use 
of 3-1 



memory management (continued) 
suballocation memory manage- 
ment 3-10 
summary 3-8 
memory management 

functions 3-8 
memory map 

memory suballocation 3-9 
memory suballocation package 

(MSP) 3-9 
message function calls 

DosGetMessage 4-30 

DoslnsMessage 4-30 

DosPutMessage 4-30 

refid = OS/2.program startup 
conventions 4-30 
message functions 

message retriever 4-30 

refid = OS/2, message 
functions 4-30 

refid = 0S/2.message 
retriever 4-30 
mode 9-130 
mode of operation 

reset mode (RM) 9-132 

set graphics rendition 
(SGR) 9-130 

set mode (SM) 9-132 
mode of operation control 
sequences 

set graphics rendition 9-130 
modes, device driver 7-7 
module definition file statements 

CODE A-51 

DATA A-52 

DESCRIPTIOISI A-54 

EXPORTS A-55 

HEAPSIZE A-57 

IMPORTS A-58 

LIBRARY A-60 

NAME A-62 

OLD A-63 

PROTMODE A-64 

SEGMENTS A-65 
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module definition file statements 
(continued) 

STACKSIZE A-67 

STUB A-68 
monitor cliain buffer 6-39 
Monitor Create 8-36, 9-60 
monitor data structure 6-39 
monitor data structures 

keystroke 9-93 

mouse 9-59 

printer 9-155 
Monitor DeRegister 8-22 
Monitor Flush 8-35, 9-60 
monitor record 6-40 
Monitor Register 8-60 
monitor support 

character device monitors 6-32 

device monitor function 
call 6-38 

device monitor record (see also 
monitor data structure) 6-40 

device monitor services 6-32 

DosMonClose 6-38 

DosMonOpen 6-38 

DosMonRead 6-38 

DosMonReg 6-38 

DosMonWrite 6-38 

keystroke monitor 
interface 6-53 
Monitor Write 8-39, 9-60 
monitors, keystroke 9-93 
monitors, mouse 9-59 
monitors, printer 9-155 
MouClose 9-53 
MouDeRegister 9-53 
MouDrawPtr 9-53, 9-56 
MouGetDevStatus 9-53 
MouGetEventMask 9-53 
MouGetNumButtons 9-53 
MouGetNumMickeys 9-53 
MouGetNumQueEl 9-53 
MouGetPtrShape 9-53 
MouGetScaleFact 9-53 



MouOpen 9-53 
MouReadEventQue 9-53 
MouRegister 9-53 
MouRemovePtr 9-53, 9-56 
Mouse - DOS mode 9-56 
Mouse - General Information 9-34 
Mouse - OS/2 mode 9-49 
Mouse - Screen Resolutions 9-36 
Mouse ABIOS 9-35 

refid = mouse.interrupt 
sharing 9-35 
Mouse API, OS/2 mode 9-53 
Mouse Control Blocks 9-45 
mouse device driver 9-34 

control blocks 9-45 

coordinates 9-52 

default pointers 9-43 

device driver packaging 9-38 

devices supported 9-34 

display modes supported 9-56 

DOS mode mouse support 9-56 

handler/router 9-51 

motion 9-52 

mouse installation 9-36 

OS/2 mode 9-49 

OS/2 mode overview 9-49 

overview 9-34, 9-56 

pointer draw 
implementation 9-39 

PS/2 9-35 

screen resolutions 9-36 
Mouse Device Driver - Control 

Blocks 9-45 
Mouse Device Driver - Default 

Pointers 9-43 
Mouse Device Driver 

Packaging 9-38 
Mouse Devices 9-34 
Mouse Devices Supported 9-34 
mouse I/O services 

DOS mode INT 33H mouse 

API 6-31 
MouClose 6-30 
MouDeRegister 6-30 
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mouse I/O services (continued) 
MouDrawPtr 6-30 
MouFlushQue 6-30 
MouGetDevStatus 6-30 
MouGetEventMask 6-30 
MouGetNumButtons 6-30 
MouGetNumMickeys 6-30 
MouGetNumQueEl 6-30 
MouGetPtrPos 6-30 
MouGetPtrShape 6-30 
MouGetScaleFact 6-30 
MoulnitReal 6-30 
MouOpen 6-30 
MouReadEventQue 6-30 
MouRegister 6-30 
MouRemovePtr 6-30 
mouse I/O function call 

summary 6-30 
mouse I/O services 6-30 
MouSetEventMask 6-30 
MouSetPtrPos 6-30 
MouSetPtrShape 6-30 
MouSetScaleFact 6-30 

Mouse Installation 9-36 

Mouse lOCtI 9-53 

Mouse lOCtI Calls 9-52 

mouse monitors 9-59 
Deregister 9-60 
MonFlush 9-60 
MonitorCreate 9-60 
MonWrite 9-60 
register 9-60 

mouse pointer draw 
Implementation 9-39 
executable commands 9-40, 
9-42 

functions supported 9-40 
pointer draw installation 9-50 

Mouse, PS/2 9-35 

MouSetDevStatus 9-53 

MouSetEventMask 9-53 

MouSetPtrShape 9-53, 9-56 

MouSetScaleFact 9-53 



MouXxx API 9-35, 9-52 
MSP memory management inter- 
faces 3-10 
multiple character device support 

per device driver 7-22 
multiple device headers per 

driver 7-2, 7-22 
Multitasking 

independent processes 4-3 

multiple threads 4-7 

refid = 0S/2.muitltasking 4-3 

N 

NAME A-62 

name/units field 7-25 

no packing code segments A-21 

NONDESTRUCTIVE READ NO 

WAIT 7-55 
NULL bit 7-24 

O 

obtaining a Logical ID, device 

drivers 7-34 
OLD statement A-63 
optimizing far calls A-1 1 

FARCALLTRANSLATION A-11 
option character (/) A-2 
options with LINK A-2 
options, using A-2 
ordering segments A-8 
OS/2 

OS/2 API 2-11 
OS/2 application 

environments 2-10 
OS/2 components 

OS/2 device driver operations 7-8 
OS/2 function calls, see function 
calls also 
Asynchronous Notification 4-25 
Control, Program 
Execution 4-29 
device driver 7-27 
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OS/2 function calls, see function 
calls also (continued) 
DosBeep 6-14 
DosDevConfIg 6-14 
OosDevlOCtI 6-14 
DoslOAccess 6-14 
DosPhyslcalDlsk 6-14 
DosSendSlgnal 6-14 
DosSleep 4-1 
DosTimerAsync 4-1 
DosTimerStop 4-1 
errors and exceptions 4-30 
exceptions and exceptions 4-30 
Interprocess 

Communication 4-23 
interval 4-3 
IPC 4-23 

Message Functions 4-30 
Message Retriever 4-30 
Multitasl<ing 4-8 
Notification 4-25 
OS/2 program selector 5-4 
Program Execution Control 4-29 
queue 4-15 
screen switclner 5-4 
Tasking 4-8 
Timer 4-3 
OS/2 interrupts, see interrupts 
OS/2 mode memory 
management 3-4 
Global InfoSeg 3-4 
Local Descriptor Table 
(LDT) 3-4 
OS/2 mode Mouse - 
Coordinates 9-52 
OS/2 mode Mouse - Display Modes 

Supported 9-56 
OS/2 mode Mouse - Events 9-54 
OS/2 mode Mouse - 

Handler/Router 9-51 
OS/2 mode Mouse - Motion 9-52 
OS/2 mode Mouse - MouXxx and 
lOCti Calls 9-52 



OS/2 mode Mouse - Overview 9-49 
OS/2 Mode Mouse - Pointer Draw 

Installation 9-50 
OS/2 mode Mogse API 9-53 
OS/2 mode Mouse Pointer 9-55 
OS/2 mode Mouse Support 9-49 
OS/2 registers, see registers, OS/2 
OS/2compatibility 

considerations 2-10 
output 

OUTPUT FLUSH 7-57 
OUTPUT STATUS 7-56 
overlays 

setting the interrupt 
number A-22 

P 

packing code segments A-23 
paragraph space A-7 
partition table 9-146 
partition table, master start-up 

record 9-146 
PARTITIONABLE FIXED 

DISKS 7-65 
Pascal interface examples 2-9 
Pascal interface, example 2-9 
permanent error processing 4-29 
PhysTo<|DTSelector 8-41 
PhysToUVirt 8-43 
PhysToVirt 8-45 
PhysToVirt rule 7-18 
pointer (screen) device driver 9-32 
Pointer Images 9-43 
position rule 7-18 
preparing files for A-6 
preparing files for CodeView A-6 
preparing for CodeView A-6 
preserving compatibility 

LINK A-19 
preserving lowercase A-20 
previous-level device drivers 7-29 
previous-level device drivers, 

Init 7-30 
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previous-level device drivers, 

install 7-30 
previous-level device drivers, 

rules 7-29 
printer Activate Font 9-158 
Printer Activate FontlOCtI 9-159 
printer device driver 9-154 
printer Font Monitor Buffer Com- 
mands 9-159, 9-161 
printer monitor record 9-159 
printer monitors 9-155 
printer Query Active Font 9-158 
Printer Query Active 

FontlOCtI 9-159 
printer Verify Font 9-159 
Printer Verify FontlOCtI 9-159 
problem determination 

functions, problem 
determination 10-1 

utilities, problem 
determination 10-1 
process control 

Intervals, asynchronous 4-1 

time/date 4-1 

timer management 4-1 

timer services 4-1 
processing interrupts 7-13 
processing interrupts, interrupt 

sharing 7-16 
producing a public symbol 

map A-16 
program execution control 

dynamic link module 4-26 

dynamic link routines 4-26 

dynamic linking 4-26 

dynamic linking, load time 4-26 

dynamic linking, run time 4-26 
program execution function calls 

DosFreeModule 4-29 

DosGetModHandle 4-29 

DosGetModName 4-29 

DosGetProcAddr 4-29 

DosLoadModule 4-29 



program segment 
protection model 3-3 
PROTMODE statement A-64 
ProtToReal 8-49 
PS/2 Mouse 9-35 
public symbol map A-16 

producing A-16 
PullParticular 8-51 
PullReqPacket 8-52 
PushReqPacket 8-53 

Q 

QSIZE 9-37 

queue element functions 

copy function 4-18 

delete function 4-18 
queue linkage field, request 

header 7-42 
QueueFlush 8-54 
queue! ng request packets, device 

driver 7-9 
Queuelnit 8-55 
QueueRead 8-56 
QueueWrite 8-57 

R 

READ (input) 7-53 

real memory map, compatibility 

mode 3-6 
real memory map, protect 

mode 3-6 
real mode memory map 3-6 
RealToProt 8-58 
reassign keys 9-133 
Register 9-60 
registers, OS/2 
REMOVABLE MEDIA 7-59 
removable media bit 7-24 
replacing character device 

drivers 7-28 
request handling 7-8 
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request header 7-37 

command-specific data 
field 7-42 

queue linl<age field 7-42 

status word 7-40 
request header command-specific 

field 7-42 
request header queue linlcage 

field 7-42 
request header status error 

codes 7-41 
request header status field 7-40 
request packet 7-37 
request packet format 7-38 
request packet header 7-38 
request packet queue 

management 7-9 
request to send (RTS). 9-4 
reserving paragraph space A-7 
RESET MEDIA 7-61 
ResetTimer 8-62 
resource management 

files 4-8 

memory 4-8 

pipes 4-8 

queues 4-8 

system semaphores 4-8 
restore cursor position 9-130 
ring structure 3-2 

protect features of 3-2 
ROMCritSection 8-63 
routines 

routines, strategy 7-24 
RS232-C/COM 9-1 
rule, ABIOS eoi placement 7-18 
rule, ABIOS LID IRQ 7-18 
rule, ABIOS request block 7-18 
rule, BIOS interrupt 7-15 
rule, DOS mode sharing 7-15 
rule, eoi 7-17 

rule, ill-behaved device 7-15 

rule, int return 7-17 

rule, irq enforcement 7-15 



rule, Irq mask 7-16 
rule, irq ownership 7-16 
rule, PhysToVirt 7-18 
rule, position 7-18 
rule, search rule 7-17 
rule, set irq 7-15 
rule, sti entry 7-16 
rule, system timer 7-14 
rules, interface 2-3 
Run 8-65 

run file loading A-13 

run time dynamic linking 4-26 

s 

save cursor position 9-129 
SchedClockAddr 8-66 
screen cursor control 9-125 
Screen Resolutions 9-36 
search rule 7-17 
sector alignment A-5 
segment A-5 
segment order A-8 
segmentation hardware 3-1 
segments A-21,A-23 

no packing code segments A-21 

packing code segments A-23 
SEGMENTS statement A-65 
segments, setting the 

number A-25 
semaphore function calls 

DosCloseSem 4-22 

DosCreateSem 4-22 

DosMuxSemWait 4-22 

DosOpenSem 4-22 

DosResumeThread 4-22 

DosSemClear 4-21 

DosSemRequest 4-21 

DosSemSet 4-22 

DosSemSetWait 4-22 

DosSemWait 4-22 

DosSuspendThread 4-22 

signalling 4-21 
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semaphore management 7-1 1 
SemClear 8-68 
SemHandle 8-70 
Sem Request 8-73 
SendEvent 8-75 
SERIAL 9-36 

serial communicatlons/COM 9-1 
Serial Mouse Interrupt 

Sharing 9-35 
Serviceability Functions 10-2 
session management 5-1 
session manager application 

support 5-3 
set 

set graphics rendition, control 
sequence 9-130 

set interrupt vector 4-30 

set Irq rule 7-15 

SET LOGICAL DRIVE MAP 7-62 

SetlRQ 8-77 

SetROMVector 8-78 

SetTimer 8-80 

setting stack size A-26 

setting the overlay interrupt A-22 

setting the sector alignment 
factor A-5 

setting the segment sector align- 
ment factor A-5 

shared bit 7-24 

shared interrupt architecture 7-13 
small model, device driver 7-21 
software interrupt handler 7-6 
software interrupt handler, device 

driver 7-6 
SortReqPacket 8-82 
spooler monitor 6-57 
spooler operational 
description 6-57 
STACK class name A-8 
stack frame 2-6 
stack size, setting A-26 
STACKSIZE statement A-67 
Stand-alone Dump Facility 10-2, 

10-5 



standard input bit 7-24 
standard output bit 7-24 
state of the COM port 9-10 
statements, module definition 
file A-50 

CODE A-51 

DATA A-52 

DESCRIPTION A-54 

EXPORTS A-55 

HEAPSIZE A-57 

IMPORTS A-58 

LIBRARY A-60 

NAME A-62 

OLD A-63 

PROTMODE A-64 

SEGMENTS A-65 

STACKSIZE A-67 

STUB A-68 
Status field 7-40 
status field error codes 7-41 
status field, request header 7-40 
status word 7-40 
status word bits 

busy 7-40 

done 7-41 

error 7-40 

error code 7-41 
sti entry rule 7-16 
strategy routine 7-8 
strategy routine, device driver 7-5 
strategy routines 7-24 
structure, monitor data 6-39 
STUB statement A-68 
support of previous-level device 

drivers 7-29 
system extensions 3-1 1 
system initialization 

device driver installation 6-13 

hardware characteristics 6-13 
system timer rule 7-14 
System Trace 10-3 
System Trace Facility 10-2, 10-3 
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T 

task-time 7-7 

Tasking (processes and tlireads) 

communicate between 
processes 4-4 

coordinate execution 4-4 

execute programs 4-4 

initiate other processes 4-4 

terminate otiier processes 4-4 
tasking function caiis 

DosCreateTliread 4-8 

DosCwait 4-8 

DosEnterCritSec 4-8 

DosExecPgm 4-8 

DosExit 4-8 

DosExitCritSec 4-8 

DosGetlnfoSeg 4-8 

DosGetPrty 4-8 

DosKillProcess 4-8 

DosSetPrty 4-8 
TCYIeld 8-83 
TickCount 8-84 
time 

Time services 4-1 
timer function caiis 

DosGetDateTime 4-3 

DosSetDateTime 4-3 

DosSieep 4-3 

DosTimerAsync 4-3 

DosTimerStart 4-3 

DosTimerStop 4-3 
timer liandler 7-6 
timer handler, device driver 7-6 
Timer services 4-1 
Trace Facility 10-2, 10-3 
Trace Formatter Utility 10-7 
TRACEBUF and TRACE 

commands 10-3 
TRACEFMT, Trace Formatter 

Utility 10-7 
translation A-18 
types of devices 



u 

Unlock 8-86 
UnPhysToVirt 8-87 
UnSetlRQ 8-89 
User Mode 7-7 
using advanced BIOS 7-33 
Using System Trace 10-3 
Utility, Create Dump Diskette 10-2, 
10-9 

Utility, Trace Formatter 10-7 

V 

VerifyAccess 8-90 
vertical position 9-127 
video font file header 6-23 
video font file organization 6-23 
video font table format 6-24 
Video Graphics Array (VGA) 6-16 
viewing the options list A-12 
VIO code page support 6-21 
VtO function call summary 

VioEndPopUp 6-26 

VioGetAnsi 6-26 

VioGetBuf 6-26 

VioGetConfig 6-26 

VioGetCp 6-26 

VioGetCurPos 6-26 

VioGetCurType 6-26 

VioGetFont 6-26 

VioGetMode 6-26 

VioGetPhysBuf 6-26 

VioGetState 6-26 

VioModeUndo 6-26 

VioModeWait 6-26 

VioPopUp 6-26 

VioPrtSc 6-26 

VioPrtScToggle 6-26 

VioReadCeliStr 6-26 

VioReadCharStr 6-26 

VioRegister 6-26 

VioSavRedrawUndo 6-26 

VioSavRedrawWait 6-26 

VioScrLock 6-26 
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VIO function call summary (con- 
tinued) 

VioScrollDn 6-26 

VioScrollLf 6-26 

VioScrolIRt 6-26 

VioScrollUp 6-26 

VioScrUnLock 6-26 

VioSetAnsi 6-26 

VioSetCp 6-26 

VioSetCurPos 6-26 

VioSetCurType 6-26 

VioSetFont 6-26 

VioSetMode 6-26 

VioSetState 6-26 

VioShowBuf 6-26 

VioWrtCeliStr 6-26 

VioWrtCharStr 6-26 

VioWrtCharStrAtt 6-26 

VioWrtNAttr 6-26 

VioWrtNCell 6-26 

VioWrtNChar 6-26 

VioWrtTTY 6-26 
VIO screen save/restore 

operations 6-20 
VirtToPhys 8-92 
Virtual Disk device driver 

W 

warning of incorrect offset A-27 
well-behaved devices 7-15 
WRITE (output) 7-53 
WRITE (output) WITH VERIFY 7-53 

Y 

Yield 8-93 

communications device 
driver 9-1 



Numerics 

2FH multiplex Interrupt 
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